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).
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
py 3.13
✕ build_error
✕ build_error
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
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.