Registry / aws / localstack-ext

localstack-ext

JSON →
library2026.3.0pypypiunverified

LocalStack Extensions (`localstack-ext`) is a Python library that enables developers to extend and customize LocalStack, a fully functional local cloud stack. Extensions run as Python applications within the LocalStack container, allowing for new service emulators, modifications to existing services, and custom functionality. The library is currently at version 2026.3.0 and follows a monthly calendar versioning cadence (YYYY.MM.patch).

pip install localstack-ext
INSTALL
IMPORT
SIG · LOCALSTACK-EXT
L
localstack-ext
awspythonv2026.3.0
Install
21.8s avg
Import
Disk
150MB
Pass rate
8/ 10
Env Coverage8 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v4.14.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
glibc
py 3.10
✓ —
✓ 18.43s
py 3.11
✓ —
✓ 16.6s
py 3.12
✓ —
✓ 15.98s
py 3.13
✕ build_error
✕ build_error
py 3.9
✓ —
✓ 36.15s
150MB installed
● package 150MB
Code
Verified usage

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

Extension
from localstack_ext.api import Extension
from localstack_ext.api import Extension

This quickstart demonstrates how to create a basic LocalStack extension that announces its readiness when the LocalStack platform is fully started. Extensions are Python classes inheriting from `localstack.extensions.api.Extension` and registered via a Python entry point. After packaging and installing the extension using the `localstack extensions install` CLI command, it will be loaded by the LocalStack runtime.

import logging from localstack.extensions.api import Extension LOG = logging.getLogger(__name__) class MyReadyAnnouncerExtension(Extension): """ A minimal LocalStack extension that logs a message when LocalStack is ready. """ name = "my-ready-announcer-extension" def on_platform_ready(self): """ Called when LocalStack is fully ready and the Ready marker has been printed. """ # Replace 'YOUR_AUTH_TOKEN_HERE' with a real token or use os.environ.get('LOCALSTACK_AUTH_TOKEN', '') # if this code were part of a larger application that manages LocalStack itself. # For an extension, the token is typically set for the LocalStack runtime it operates within. LOG.info(f"Extension '{self.name}' is loaded and LocalStack is ready to roll!") # To use this extension: # 1. Save it as a Python file (e.g., `my_extension.py`) within a Python package structure. # 2. Define an entry point in your `pyproject.toml` or `setup.py` (e.g., under `[options.entry_points]`): # `localstack.extensions = my_ready_announcer = my_extension_module:MyReadyAnnouncerExtension` # 3. Install the extension into LocalStack using the CLI: `localstack extensions install .` (from the package root) # 4. Start LocalStack. The log message will appear in LocalStack's logs when it's ready.
localstack --version
Debug
Known issues
breakingLocalStack (and its associated components like localstack-ext) adopted calendar versioning (YYYY.MM.patch) starting with the March 2026 release. This means version numbers like `2026.03.0` instead of traditional semantic versioning. Users should adjust their version pinning accordingly.
fix
Update version constraints in `requirements.txt` or `pyproject.toml` to reflect the new YYYY.MM.patch format (e.g., `localstack-ext>=2026.03.0,<2026.04.0`).
affects: >=2026.03.0
breakingAs of March 23, 2026, the `localstack/localstack:latest` Docker image and other LocalStack components now require authentication via a `LOCALSTACK_AUTH_TOKEN`. Running LocalStack (which hosts `localstack-ext` extensions) without this token will result in authentication errors.
fix
Sign up for a free LocalStack account, generate an auth token from the LocalStack Web App, and set it as the `LOCALSTACK_AUTH_TOKEN` environment variable before starting LocalStack. The `localstack auth login` CLI command is deprecated in favor of this approach.
affects: >=2026.03.0
gotchaThe LocalStack Extensions API is currently in a 'preview' stage and may be subject to future changes. This means that future updates to `localstack-ext` might introduce breaking changes to the extension development API.
fix
Monitor the official LocalStack documentation and GitHub repository for `localstack-extensions` for announcements on API stability and migration guides.
affects: All versions
gotchaInstalling `localstack-ext` (or the core `localstack` package that depends on it) into a global Python environment can lead to dependency conflicts (`subprocess-exited-with-error`).
fix
It is highly recommended to install `localstack-ext` within an isolated Python environment using tools like `venv` or `pipx` to avoid conflicts with other installed packages.
affects: All versions
gotchaWhile extensions run in the same Python process as LocalStack and can technically import internal LocalStack modules, doing so is discouraged. These internal modules are not part of the public API and can change in patch versions, potentially breaking your extension.
fix
Rely only on the officially documented `localstack.extensions.api` for extension development to ensure forward compatibility and receive support.
affects: All versions
gotchaLocalStack extensions are installed into a dedicated virtual environment within the LocalStack volume (default `~/.cache/localstack`). If you customize the `LOCALSTACK_VOLUME_DIR` for your LocalStack instance, you must explicitly specify this path before installing extensions to ensure they are persisted and correctly loaded.
fix
Ensure `LOCALSTACK_VOLUME_DIR` is correctly configured in your LocalStack environment (e.g., Docker Compose) and, if different from default, specify it when using `localstack extensions install`.
affects: All versions
Upgrade
Version history
2026.3.0latest on PyPI · released Mar 23, 2026
Audit
Dependencies
localstackrequiredlocalstack-ext is an extension *for* LocalStack; LocalStack (the cloud emulator runtime) is required for extensions to function.
pythonrequiredRequired Python version range.
Agent activity
22 hits · last 30 days
node
20
Resources
localstack-ext — pip install localstack-ext · libregistry