{"id":6395,"library":"localstack-ext","title":"LocalStack Extensions","description":"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).","status":"active","version":"2026.3.0","language":"en","source_language":"en","source_url":"https://github.com/localstack/localstack-extensions","tags":["LocalStack","AWS","cloud emulator","extension","development","testing","mocking"],"install":[{"cmd":"pip install localstack-ext","lang":"bash","label":"Install `localstack-ext` Python package"}],"dependencies":[{"reason":"localstack-ext is an extension *for* LocalStack; LocalStack (the cloud emulator runtime) is required for extensions to function.","package":"localstack","optional":false},{"reason":"Required Python version range.","package":"python","optional":false}],"imports":[{"note":"This is the base class for defining custom LocalStack extensions.","symbol":"Extension","correct":"from localstack.extensions.api import Extension"}],"quickstart":{"code":"import logging\nfrom localstack.extensions.api import Extension\n\nLOG = logging.getLogger(__name__)\n\nclass MyReadyAnnouncerExtension(Extension):\n    \"\"\"\n    A minimal LocalStack extension that logs a message when LocalStack is ready.\n    \"\"\"\n    name = \"my-ready-announcer-extension\"\n\n    def on_platform_ready(self):\n        \"\"\"\n        Called when LocalStack is fully ready and the Ready marker has been printed.\n        \"\"\"\n        # Replace 'YOUR_AUTH_TOKEN_HERE' with a real token or use os.environ.get('LOCALSTACK_AUTH_TOKEN', '')\n        # if this code were part of a larger application that manages LocalStack itself.\n        # For an extension, the token is typically set for the LocalStack runtime it operates within.\n        LOG.info(f\"Extension '{self.name}' is loaded and LocalStack is ready to roll!\")\n\n# To use this extension:\n# 1. Save it as a Python file (e.g., `my_extension.py`) within a Python package structure.\n# 2. Define an entry point in your `pyproject.toml` or `setup.py` (e.g., under `[options.entry_points]`):\n#    `localstack.extensions = my_ready_announcer = my_extension_module:MyReadyAnnouncerExtension`\n# 3. Install the extension into LocalStack using the CLI: `localstack extensions install .` (from the package root)\n# 4. Start LocalStack. The log message will appear in LocalStack's logs when it's ready.\n","lang":"python","description":"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."},"warnings":[{"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`).","message":"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.","severity":"breaking","affected_versions":">=2026.03.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=2026.03.0"},{"fix":"Monitor the official LocalStack documentation and GitHub repository for `localstack-extensions` for announcements on API stability and migration guides.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Rely only on the officially documented `localstack.extensions.api` for extension development to ensure forward compatibility and receive support.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}