Registry / aws / localstack-client

localstack-client

JSON →
library2.12pypypi✓ verified 22d ago

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.

pip install localstack-client
INSTALL
IMPORT
SIG · LOCALSTACK-CLIENT
L
localstack-client
awspythonv2.12
Install
4.6s avg
Import
683ms
Disk
51MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2.12 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.702s · 52.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 4.6s · import 0.664s · 53MB
51MB installed
● package 51MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Session
from localstack_client.session import Session
import boto3
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.

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.

import os from localstack_client.session import Session # Ensure LocalStack is running before executing this code. # If running LocalStack in Docker, make sure port 4566 is mapped. # You can optionally set AWS_ENDPOINT_URL, but localstack-client defaults to localhost:4566 # os.environ['AWS_ENDPOINT_URL'] = 'http://localhost:4566' session = Session() s3_client = session.client('s3') try: # Create a bucket (ensure it doesn't already exist) bucket_name = 'my-local-bucket-123' s3_client.create_bucket(Bucket=bucket_name) print(f"Bucket '{bucket_name}' created successfully.") # List buckets to verify response = s3_client.list_buckets() print("\nExisting buckets:") for bucket in response['Buckets']: print(f"- {bucket['Name']}") # Upload a file file_content = b'Hello from LocalStack!' file_name = 'hello.txt' s3_client.put_object(Bucket=bucket_name, Key=file_name, Body=file_content) print(f"\nFile '{file_name}' uploaded to '{bucket_name}'.") # Download the file download_response = s3_client.get_object(Bucket=bucket_name, Key=file_name) downloaded_content = download_response['Body'].read().decode('utf-8') print(f"\nDownloaded content: '{downloaded_content}'") except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
breakingThe environment variables `LOCALSTACK_HOST` and `USE_SSL` are deprecated for configuring the LocalStack endpoint. They have been superseded by `AWS_ENDPOINT_URL`.
fix
Migrate your configuration to use `AWS_ENDPOINT_URL`. For example, set `os.environ['AWS_ENDPOINT_URL'] = 'http://localhost:4566'` before initializing the session.
affects: All versions, especially when upgrading LocalStack server to v3/v4 or higher.
gotchaThe `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.
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`).
affects: All versions
gotchaWhen 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.
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.
affects: All versions
gotchaThe `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.
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.
affects: All versions
gotchaLocalStack (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.
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`).
affects: LocalStack 3.x, 4.x and above (not directly localstack-client versions).
Errors
Common errors & fixes
botocore.exceptions.EndpointConnectionError: Could not connect to the endpoint URL:
This error occurs when the `localstack-client` or underlying boto3 client cannot establish a connection to the LocalStack instance, often because LocalStack is not running, is configured on a different port, or network settings (especially in Docker environments) prevent access.
fix
Ensure your LocalStack instance is running (e.g., `docker-compose up -d`), verify its exposed port (default 4566), and if your client code is running inside another Docker container, use `http://host.docker.internal:4566` (for Docker Desktop) or the LocalStack container's service name/IP as the `endpoint_url` in your boto3 client configuration.
Connection refused
A 'Connection refused' error typically means the Python client tried to connect to a port on a server, but the server actively refused the connection. This often happens if LocalStack isn't running or the specified port is incorrect/blocked.
fix
Confirm LocalStack is running and listening on the expected port (usually 4566). Check `docker-compose ps` if using Docker Compose, or `netstat` on your host. If running in Docker, ensure proper port mapping and connectivity between containers or to the host.
ModuleNotFoundError: No module named 'localstack_client'
The Python interpreter cannot find the `localstack-client` package, indicating it is either not installed in the current environment or the environment is not correctly activated.
fix
Install the library using pip: `pip install localstack-client`. If you are using a virtual environment, make sure it is activated before installation.
botocore.exceptions.NoCredentialsError: Unable to locate credentials
This error arises when the boto3 client, even when configured for LocalStack, attempts to make a call that requires AWS credentials (e.g., when falling back to a real AWS endpoint due to misconfiguration or for some specific service interactions) but cannot find any.
fix
When creating a boto3 client, ensure `endpoint_url` is explicitly set to your LocalStack instance (e.g., `http://localhost:4566`) to prevent calls to real AWS. Additionally, provide dummy AWS credentials (e.g., `aws_access_key_id='test'`, `aws_secret_access_key='test'`, `region_name='us-east-1'`) in your client creation or as environment variables for consistent LocalStack interaction.
Upgrade
Version history
2.12latest on PyPI · released Jul 21, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
9 hits · last 30 days
node
8
Resources
localstack-client — pip install localstack-client · libregistry