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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 64.8MB
glibcpy 3.10–3.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`).fixWhen 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.fixAlways 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`.fixAlways 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.fixTo 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.fixEnsure 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.