{"id":4617,"library":"localstack-client","title":"LocalStack Python Client","description":"The localstack-client is a lightweight Python client designed to facilitate interaction with LocalStack, a cloud service emulator. It provides a thin wrapper around the popular boto3 library, automatically configuring endpoint URLs to point to your local LocalStack instance. The library is actively maintained with frequent releases; version 2.11 was released in January 2026.","status":"active","version":"2.11","language":"en","source_language":"en","source_url":"https://github.com/localstack/localstack-python-client","tags":["aws","localstack","testing","cloud","mocking","boto3"],"install":[{"cmd":"pip install localstack-client","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"While 'import localstack_client.session as boto3' is a common pattern for transparent usage, directly importing 'boto3' will bypass LocalStack and connect to real AWS services unless you manually configure the endpoint_url in every client instantiation.","wrong":"import boto3","symbol":"Session","correct":"from localstack_client.session import Session"}],"quickstart":{"code":"import os\nfrom localstack_client.session import Session\n\n# Ensure LocalStack is running before executing this code.\n# If running LocalStack in Docker, make sure port 4566 is mapped.\n\n# You can optionally set AWS_ENDPOINT_URL, but localstack-client defaults to localhost:4566\n# os.environ['AWS_ENDPOINT_URL'] = 'http://localhost:4566'\n\nsession = Session()\ns3_client = session.client('s3')\n\ntry:\n    # Create a bucket (ensure it doesn't already exist)\n    bucket_name = 'my-local-bucket-123'\n    s3_client.create_bucket(Bucket=bucket_name)\n    print(f\"Bucket '{bucket_name}' created successfully.\")\n\n    # List buckets to verify\n    response = s3_client.list_buckets()\n    print(\"\\nExisting buckets:\")\n    for bucket in response['Buckets']:\n        print(f\"- {bucket['Name']}\")\n\n    # Upload a file\n    file_content = b'Hello from LocalStack!'\n    file_name = 'hello.txt'\n    s3_client.put_object(Bucket=bucket_name, Key=file_name, Body=file_content)\n    print(f\"\\nFile '{file_name}' uploaded to '{bucket_name}'.\")\n\n    # Download the file\n    download_response = s3_client.get_object(Bucket=bucket_name, Key=file_name)\n    downloaded_content = download_response['Body'].read().decode('utf-8')\n    print(f\"\\nDownloaded content: '{downloaded_content}'\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize a session with localstack-client and interact with a local S3 service. It creates a bucket, uploads a file, lists buckets, and downloads the file, all against a running LocalStack instance. Remember that a LocalStack instance must be running and accessible before executing this code."},"warnings":[{"fix":"Migrate your configuration to use `AWS_ENDPOINT_URL`. For example, set `os.environ['AWS_ENDPOINT_URL'] = 'http://localhost:4566'` before initializing the session.","message":"The environment variables `LOCALSTACK_HOST` and `USE_SSL` are deprecated for configuring the LocalStack endpoint. They have been superseded by `AWS_ENDPOINT_URL`.","severity":"breaking","affected_versions":"All versions, especially when upgrading LocalStack server to v3/v4 or higher."},{"fix":"Ensure you have LocalStack installed (e.g., via `pip install localstack` and `localstack start`) and that the Docker container is running and accessible (typically on `localhost:4566`).","message":"The `localstack-client` library acts as a wrapper for `boto3` to connect to LocalStack. It requires an *active and running* LocalStack instance to function. Without it, operations will fail.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use appropriate hostnames like `host.docker.internal` (Docker Desktop), or configure your Docker network and `AWS_ENDPOINT_URL` environment variable to point to the correct IP address or service name for LocalStack. Consult LocalStack's networking documentation for specific scenarios.","message":"When running applications (e.g., AWS Lambda functions, Docker containers) that need to connect to LocalStack, direct usage of `localhost` or `127.0.0.1` from within those containers might not work due to networking isolation. LocalStack itself only binds to IPv4 addresses.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Regularly update your LocalStack Docker image (e.g., `localstack update docker-images` or by pulling the `latest` or a specific version tag for `localstack/localstack-pro` Docker image). Consult LocalStack's release notes and feature coverage for service-specific compatibility.","message":"The `localstack-client` is a thin wrapper. Compatibility with specific AWS service behaviors relies heavily on the underlying LocalStack version. New or changed AWS API features might not be supported if your LocalStack instance is outdated, or conversely, older LocalStack versions might have compatibility issues with newer AWS SDK (boto3) features.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the LocalStack upgrade guides for versions 3.0 and 4.0 to understand necessary environment and configuration adjustments. Always ensure your LocalStack CLI is up-to-date (`pip install --upgrade localstack`).","message":"LocalStack (the emulator) has undergone significant breaking changes in versions 3.0 and 4.0, including changes to configuration variables (e.g., removal of `AUTOSTART_UTIL_CONTAINERS`, changes to CloudPods client) and authentication methods (`localstack auth login` deprecated). These changes in the core LocalStack platform can indirectly affect how you set up your environment for the Python client.","severity":"gotcha","affected_versions":"LocalStack 3.x, 4.x and above (not directly localstack-client versions)."}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}