LocalStack Core

Warnings

• breaking 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.
  Fix: Be aware of the new versioning scheme for updates and compatibility. YYYY.MM represents the year and month of the release.
• breaking 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.
  Fix: Obtain a LocalStack auth token from your account and set it as the `LOCALSTACK_AUTH_TOKEN` environment variable before starting LocalStack.
• breaking 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.
  Fix: Update your Docker image references to `localstack/localstack` and ensure `LOCALSTACK_AUTH_TOKEN` is configured to access appropriate service entitlements.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

• pip install localstack-core Install localstack-core library
• pip install localstack # For the LocalStack CLI (recommended for general use) Install LocalStack CLI

Imports

• Extension

  from localstack.extensions.api import Extension

  Used for developing custom LocalStack extensions.

Quickstart

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.

import logging
from localstack.extensions.api import Extension

LOG = logging.getLogger(__name__)

class ReadyAnnouncerExtension(Extension):
    name = "my_ready_announcer"

    def on_platform_ready(self):
        LOG.info("My custom extension is loaded and LocalStack is ready!")

# To run this, you would typically save it as a Python file (e.g., my_extension.py)
# and install it as a LocalStack extension, often via the LocalStack CLI:
# 1. Ensure LocalStack CLI is installed: pip install localstack
# 2. Start LocalStack (requires Docker): localstack start
# 3. Install the extension using its entry point configuration (e.g., in setup.py/cfg)
#    or directly from a file/git repo using `localstack extensions install`.
#    For demonstration, if packaged:
#    localstack extensions install my-ready-announcer
#    (This example shows the Python code for an extension, not how to run a standalone script with localstack-core)

# A more direct, though less common, 'quickstart' for *using* LocalStack from Python
# would involve the AWS SDK (boto3) configured to talk to LocalStack endpoints.
# This is typically done with `awslocal` or direct endpoint configuration.
# Example for boto3 (requires LocalStack running):
# import boto3
# import os
#
# os.environ['AWS_ACCESS_KEY_ID'] = 'test'
# os.environ['AWS_SECRET_ACCESS_KEY'] = 'test'
# os.environ['AWS_DEFAULT_REGION'] = 'us-east-1'
#
# s3_client = boto3.client('s3', endpoint_url='http://localhost:4566')
# try:
#     response = s3_client.list_buckets()
#     print(f"S3 Buckets (LocalStack): {response['Buckets']}")
# except Exception as e:
#     print(f"Error connecting to LocalStack S3: {e}")