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).

awsdevops
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.

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 footguns
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.
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.
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.
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`).
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.
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.
Upgrade
Version history

Breaking-change detection hasn't run for this library yet.

Audit
Security & dependencies

CVE tracking and dependency tree are planned for a later release.

Agent activity
29 hits · last 30 days
gptbot
4
ahrefsbot
4
amazonbot
4
bytedance
3
dotbot
2
script
1
googlebot
1
Resources