{"id":3542,"library":"localstack-core","title":"LocalStack Core","description":"LocalStack Core is the foundational Python library and runtime for LocalStack, a robust cloud service emulator that allows developers to run AWS applications and Lambdas entirely on their local machine or in CI environments without connecting to a remote cloud provider. The library underpins the LocalStack CLI and Docker container, providing the core emulation capabilities. As of the 2026.03.0 release, LocalStack has adopted calendar versioning (YYYY.MM.patch) and follows a monthly release cadence.","status":"active","version":"2026.3.0","language":"en","source_language":"en","source_url":"https://github.com/localstack/localstack-core","tags":["aws","cloud emulator","local development","testing","serverless","python","development tools"],"install":[{"cmd":"pip install localstack-core","lang":"bash","label":"Install localstack-core library"},{"cmd":"pip install localstack # For the LocalStack CLI (recommended for general use)","lang":"bash","label":"Install LocalStack CLI"}],"dependencies":[],"imports":[{"note":"Used for developing custom LocalStack extensions.","symbol":"Extension","correct":"from localstack.extensions.api import Extension"}],"quickstart":{"code":"import logging\nfrom localstack.extensions.api import Extension\n\nLOG = logging.getLogger(__name__)\n\nclass ReadyAnnouncerExtension(Extension):\n    name = \"my_ready_announcer\"\n\n    def on_platform_ready(self):\n        LOG.info(\"My custom extension is loaded and LocalStack is ready!\")\n\n# To run this, you would typically save it as a Python file (e.g., my_extension.py)\n# and install it as a LocalStack extension, often via the LocalStack CLI:\n# 1. Ensure LocalStack CLI is installed: pip install localstack\n# 2. Start LocalStack (requires Docker): localstack start\n# 3. Install the extension using its entry point configuration (e.g., in setup.py/cfg)\n#    or directly from a file/git repo using `localstack extensions install`.\n#    For demonstration, if packaged:\n#    localstack extensions install my-ready-announcer\n#    (This example shows the Python code for an extension, not how to run a standalone script with localstack-core)\n\n# A more direct, though less common, 'quickstart' for *using* LocalStack from Python\n# would involve the AWS SDK (boto3) configured to talk to LocalStack endpoints.\n# This is typically done with `awslocal` or direct endpoint configuration.\n# Example for boto3 (requires LocalStack running):\n# import boto3\n# import os\n#\n# os.environ['AWS_ACCESS_KEY_ID'] = 'test'\n# os.environ['AWS_SECRET_ACCESS_KEY'] = 'test'\n# os.environ['AWS_DEFAULT_REGION'] = 'us-east-1'\n#\n# s3_client = boto3.client('s3', endpoint_url='http://localhost:4566')\n# try:\n#     response = s3_client.list_buckets()\n#     print(f\"S3 Buckets (LocalStack): {response['Buckets']}\")\n# except Exception as e:\n#     print(f\"Error connecting to LocalStack S3: {e}\")","lang":"python","description":"This quickstart demonstrates how to define a simple LocalStack extension using the `localstack-core` library's extension API. LocalStack extensions are Python classes that implement specific lifecycle hooks. For general interaction with LocalStack-emulated AWS services from Python, `boto3` is used and configured to point to LocalStack's local endpoints, typically at `http://localhost:4566`. Ensure Docker is running and LocalStack is started (e.g., via `localstack start`) before attempting to interact with emulated AWS services."},"warnings":[{"fix":"Be aware of the new versioning scheme for updates and compatibility. YYYY.MM represents the year and month of the release.","message":"LocalStack switched from semantic versioning to calendar versioning (YYYY.MM.patch) starting with the March 2026 release (2026.03.0). This changes how release versions are structured and perceived.","severity":"breaking","affected_versions":">=2026.03.0"},{"fix":"Obtain a LocalStack auth token from your account and set it as the `LOCALSTACK_AUTH_TOKEN` environment variable before starting LocalStack.","message":"As of version 2026.03.0, an authentication token (`LOCALSTACK_AUTH_TOKEN`) is required to start LocalStack for AWS, even for the unified image. Legacy API and CI keys are no longer supported.","severity":"breaking","affected_versions":">=2026.03.0"},{"fix":"Update your Docker image references to `localstack/localstack` and ensure `LOCALSTACK_AUTH_TOKEN` is configured to access appropriate service entitlements.","message":"LocalStack for AWS consolidated its 'Community' and 'Pro' Docker images into a single `localstack/localstack` image. The 'Community Edition' will no longer receive updates or security patches. Users pulling the `latest` tag from the old community image need to update their workflows and may require an auth token for service entitlements.","severity":"breaking","affected_versions":">=2026.03.0"},{"fix":"Delete existing `.volume` folders or state files and re-create your LocalStack infrastructure and data. LocalStack will display an explicit message if incompatible state is detected.","message":"Any LocalStack state (Cloud Pods, state snapshots, `PERSISTENCE=1`) created with versions prior to v4.14 may not be compatible with newer versions and will need to be recreated.","severity":"breaking","affected_versions":"<4.14"},{"fix":"Implement robust integration tests that run against LocalStack and consider targeted testing in a real (non-production) AWS environment for critical or complex interactions. Be mindful of IAM policy strictness and network characteristics when developing.","message":"LocalStack, as an emulator, may not perfectly replicate all nuanced AWS behaviors or enforce strict IAM permissions by default. This can lead to a 'works on my machine' scenario that breaks in production due to actual AWS parity differences, especially concerning IAM policies or network latency.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}