Registry / aws / localstack-core

localstack-core

JSON →
library2026.3.0pypypi✓ verified 23d ago

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.

pip install localstack-core
INSTALL
IMPORT
SIG · LOCALSTACK-CORE
L
localstack-core
awspythonv2026.3.0
Install
7.8s avg
Import
Disk
95MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2026.3.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.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 93.1MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 7.8s · import 0.000s · 94MB
95MB installed
● package 95MB
Code
Verified usage

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

Extension
from localstack.extensions.api import Extension
from localstack.extensions.api import Extension

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}")
localstack --version
Debug
Known issues
breakingLocalStack 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.
affects: >=2026.03.0
breakingAs 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.
affects: >=2026.03.0
breakingLocalStack 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.
affects: >=2026.03.0
breakingAny 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.
affects: <4.14
gotchaLocalStack, 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.
affects: All
Upgrade
Version history
2026.3.0latest on PyPI · released Mar 23, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
24 hits · last 30 days
node
22
Resources