Registry / aws / localstack

localstack

JSON →
library2026.8.0pypypi✓ verified 22d ago

LocalStack is a cloud service emulator that runs entirely on your local machine. It provides a fully functional local cloud environment for developing, testing, and debugging AWS applications without deploying to a remote cloud. This specific Python package primarily provides the `localstack` command-line interface (CLI) for managing the LocalStack container. The current version is 2026.3.0, and it follows a calendar-based release cadence, often releasing monthly or more frequently.

pip install localstack
INSTALL
IMPORT
SIG · LOCALSTACK
L
localstack
awspythonv2026.8.0
Install
12.3s avg
Import
Disk
84MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2026.8.0 · 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.000s · 64.8MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 12.3s · import 0.000s · 66MB
84MB installed
● package 84MB
Code
Verified usage

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

main
from localstack_cli import main
from localstack_cli import main

This quickstart demonstrates how to programmatically start LocalStack using its CLI via `subprocess`, wait for it to initialize, and then interact with a mocked AWS S3 service using `boto3`. It's important to have Docker running in the background for LocalStack to function.

import subprocess import time import os import boto3 def start_localstack(): print('Starting LocalStack in the background...') # Use subprocess to run 'localstack start' non-blocking # Note: Requires 'localstack' CLI to be in PATH process = subprocess.Popen(['localstack', 'start'], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True) # Give LocalStack some time to start up time.sleep(15) # Check if LocalStack is running via 'localstack status' status_output = subprocess.run(['localstack', 'status'], capture_output=True, text=True) if 'running' in status_output.stdout: print('LocalStack is running.') else: print('LocalStack failed to start or is not running correctly.') print('STDOUT:', status_output.stdout) print('STDERR:', status_output.stderr) # Optionally, terminate the Popen process if it didn't start correctly # process.terminate() # return None return process def stop_localstack(process): print('Stopping LocalStack...') subprocess.run(['localstack', 'stop']) if process: # Terminate the Popen process if it was started this way process.terminate() process.wait() print('LocalStack stopped.') def main(): localstack_process = None try: localstack_process = start_localstack() if not localstack_process: return # Now, interact with a service (e.g., S3) using boto3 print('\nInteracting with S3 on LocalStack...') s3_client = boto3.client( 's3', region_name='us-east-1', endpoint_url='http://localhost:4566', aws_access_key_id='test', aws_secret_access_key='test' ) bucket_name = 'my-local-test-bucket' try: s3_client.create_bucket(Bucket=bucket_name) print(f"Bucket '{bucket_name}' created successfully.") response = s3_client.list_buckets() print('Existing buckets:') for bucket in response['Buckets']: print(f" - {bucket['Name']}") except Exception as e: print(f"Error interacting with S3: {e}") finally: stop_localstack(localstack_process) if __name__ == '__main__': # Ensure Docker is running before executing this script # On first run, 'localstack start' will download necessary Docker images. main()
localstack --version
Debug
Known issues
gotchaThe `localstack` Python package primarily provides the CLI. For interacting with AWS services running on LocalStack, you should use `boto3` (or other AWS SDKs) and configure the `endpoint_url` to point to your LocalStack instance (e.g., `http://localhost:4566`).
fix
When creating `boto3` clients, always specify `endpoint_url` (e.g., `boto3.client('s3', endpoint_url='http://localhost:4566')`). Ensure `aws_access_key_id` and `aws_secret_access_key` are set to dummy values like 'test' if not using explicit credentials.
affects: All versions
breakingLocalStack's versioning scheme changed from semantic versioning (e.g., `1.x.y`) to calendar-based versioning (e.g., `YYYY.M.D`). Be mindful of this when checking for compatibility or specific feature availability.
fix
Always refer to the latest documentation for features and breaking changes relative to the current calendar version. Update your `pip install localstack` commands to pin to specific calendar versions if needed (e.g., `localstack==2023.1.0`).
affects: From ~v1.0 to current
deprecatedSeveral configuration environment variables have been renamed or deprecated over time. A notable example is `LOCALSTACK_HOST`, which was deprecated in favor of `LS_HOST`.
fix
Always consult the official LocalStack configuration documentation (docs.localstack.cloud/references/configuration/) for the most up-to-date environment variable names and their usage. Update your environment variables or `docker-compose` files accordingly.
affects: From v1.0 onwards
gotchaPersistence is not enabled by default. If LocalStack restarts without persistence configured, all your data (e.g., S3 buckets, DynamoDB tables) will be lost.
fix
To enable persistence, set the `DATA_DIR` environment variable to a host directory where LocalStack can store its data (e.g., `DATA_DIR=/tmp/localstack/data`). This is typically done via `docker-compose.yaml` or as an environment variable when running `localstack start`.
affects: All versions
gotchaLocalStack requires Docker to be running on your system. It relies heavily on Docker containers for providing its emulated services. Without Docker, `localstack start` will fail.
fix
Ensure Docker Desktop or Docker Engine is installed and running before attempting to start LocalStack. Troubleshoot Docker issues independently if LocalStack fails to start.
affects: All versions
Upgrade
Version history
2026.8.0latest on PyPI · released Aug 26, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
24 hits · last 30 days
node
22
Resources
localstack — pip install localstack · libregistry