{"id":4618,"library":"localstack","title":"LocalStack CLI (Python Package)","description":"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.","status":"active","version":"2026.3.0","language":"en","source_language":"en","source_url":"https://github.com/localstack/localstack.git","tags":["aws","cloud","testing","development","emulator","local","docker","cli"],"install":[{"cmd":"pip install localstack","lang":"bash","label":"Install LocalStack CLI"}],"dependencies":[],"imports":[{"note":"This import is for programmatically invoking the LocalStack CLI entry point (e.g., in advanced automation scripts). For interacting with AWS services running on LocalStack, `boto3` (configured with `endpoint_url`) is the standard method, not this package directly.","symbol":"main","correct":"from localstack.main import main"},{"note":"While `boto3` is not part of the `localstack` package, it's the primary way Python developers interact with AWS services provided by LocalStack. The `endpoint_url` is crucial to direct `boto3` calls to your local LocalStack instance.","symbol":"boto3.client","correct":"import boto3; client = boto3.client('s3', endpoint_url='http://localhost:4566')"}],"quickstart":{"code":"import subprocess\nimport time\nimport os\nimport boto3\n\ndef start_localstack():\n    print('Starting LocalStack in the background...')\n    # Use subprocess to run 'localstack start' non-blocking\n    # Note: Requires 'localstack' CLI to be in PATH\n    process = subprocess.Popen(['localstack', 'start'], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)\n    # Give LocalStack some time to start up\n    time.sleep(15) \n    # Check if LocalStack is running via 'localstack status'\n    status_output = subprocess.run(['localstack', 'status'], capture_output=True, text=True)\n    if 'running' in status_output.stdout:\n        print('LocalStack is running.')\n    else:\n        print('LocalStack failed to start or is not running correctly.')\n        print('STDOUT:', status_output.stdout)\n        print('STDERR:', status_output.stderr)\n        # Optionally, terminate the Popen process if it didn't start correctly\n        # process.terminate()\n        # return None\n    return process\n\ndef stop_localstack(process):\n    print('Stopping LocalStack...')\n    subprocess.run(['localstack', 'stop'])\n    if process: # Terminate the Popen process if it was started this way\n        process.terminate()\n        process.wait()\n    print('LocalStack stopped.')\n\ndef main():\n    localstack_process = None\n    try:\n        localstack_process = start_localstack()\n        if not localstack_process:\n            return\n\n        # Now, interact with a service (e.g., S3) using boto3\n        print('\\nInteracting with S3 on LocalStack...')\n        s3_client = boto3.client(\n            's3',\n            region_name='us-east-1',\n            endpoint_url='http://localhost:4566',\n            aws_access_key_id='test',\n            aws_secret_access_key='test'\n        )\n\n        bucket_name = 'my-local-test-bucket'\n        try:\n            s3_client.create_bucket(Bucket=bucket_name)\n            print(f\"Bucket '{bucket_name}' created successfully.\")\n\n            response = s3_client.list_buckets()\n            print('Existing buckets:')\n            for bucket in response['Buckets']:\n                print(f\"  - {bucket['Name']}\")\n\n        except Exception as e:\n            print(f\"Error interacting with S3: {e}\")\n\n    finally:\n        stop_localstack(localstack_process)\n\nif __name__ == '__main__':\n    # Ensure Docker is running before executing this script\n    # On first run, 'localstack start' will download necessary Docker images.\n    main()\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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`).","severity":"gotcha","affected_versions":"All versions"},{"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`).","message":"LocalStack'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.","severity":"breaking","affected_versions":"From ~v1.0 to current"},{"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.","message":"Several configuration environment variables have been renamed or deprecated over time. A notable example is `LOCALSTACK_HOST`, which was deprecated in favor of `LS_HOST`.","severity":"deprecated","affected_versions":"From v1.0 onwards"},{"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`.","message":"Persistence is not enabled by default. If LocalStack restarts without persistence configured, all your data (e.g., S3 buckets, DynamoDB tables) will be lost.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"LocalStack 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}