LocalStack Extensions

Warnings

• breaking LocalStack (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`).
• breaking As 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.
• gotcha The 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.
• gotcha Installing `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.
• gotcha While 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.
• gotcha LocalStack 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`.

Install

• pip install localstack-ext Install `localstack-ext` Python package

Imports

• Extension

  from localstack.extensions.api import Extension

  This is the base class for defining custom LocalStack extensions.

Quickstart

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.