[!IMPORTANT] Project Update: Consolidation into the Unified LocalStack Image

To provide a more reliable and streamlined experience, we are consolidating our development into a single, unified image. As part of this transition, this repository is now archived and read-only.

This decision reflects our commitment to reducing fragmentation and focusing our resources on building the most robust AWS emulation layer possible. We are deeply grateful to the contributors who helped make this project into what it is today–your work remains integral to the future of the LocalStack ecosystem.

What this means for your workflow:

LocalStack for AWS offers a range of options including a free Hobby plan for non-commercial use with the same capabilities as this project.

Your input is still vital to us. Please continue to share bug reports here and submit feature requests here or join our Slack Community.

Thank you for your continued support as we grow together.

<img src="docs/localstack-readme-banner.svg" alt="LocalStack - The Leading Platform for Local Cloud Development"> <a href="https://github.com/localstack/localstack/actions/workflows/aws-main.yml?query=branch%3Amain"><img alt="GitHub Actions" src="https://github.com/localstack/localstack/actions/workflows/aws-main.yml/badge.svg?branch=main"></a> <a href="https://coveralls.io/github/localstack/localstack?branch=main"><img alt="Coverage Status" src="https://coveralls.io/repos/github/localstack/localstack/badge.svg?branch=main"></a> <a href="https://pypi.org/project/localstack/"><img alt="PyPI Version" src="https://img.shields.io/pypi/v/localstack?color=blue"></a> <a href="https://hub.docker.com/r/localstack/localstack"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/localstack/localstack"></a> <a href="https://pypi.org/project/localstack"><img alt="PyPi downloads" src="https://static.pepy.tech/badge/localstack"></a> <a href="https://img.shields.io/pypi/l/localstack.svg"><img alt="PyPI License" src="https://img.shields.io/pypi/l/localstack.svg"></a> <a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a> <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a> <a href="https://bsky.app/profile/localstack.cloud"><img alt="Bluesky" src="https://img.shields.io/badge/bluesky-Follow-blue?logo=bluesky"></a> LocalStack is a cloud software development framework to develop and test your AWS applications locally. <a href="#overview">Overview</a> • <a href="#install">Install</a> • <a href="#quickstart">Quickstart</a> • <a href="#running">Run</a> • <a href="#usage">Usage</a> • <a href="#releases">Releases</a> • <a href="#contributing">Contributing</a> <a href="https://docs.localstack.cloud" target="_blank">📖 Docs</a> • <a href="https://www.localstack.cloud/localstack-for-aws" target="_blank">💻 LocalStack for AWS</a> • <a href="https://docs.localstack.cloud/references/coverage/" target="_blank">☑️ LocalStack coverage</a>

Overview

LocalStack is a cloud service emulator that runs in a single container on your laptop or in your CI environment. With LocalStack, you can run your AWS applications or Lambdas entirely on your local machine without connecting to a remote cloud provider! Whether you are testing complex CDK applications or Terraform configurations, or just beginning to learn about AWS services, LocalStack helps speed up and simplify your testing and development workflow.

LocalStack supports a growing number of AWS services, like AWS Lambda, S3, DynamoDB, Kinesis, SQS, SNS, and many more! The Pro version of LocalStack supports additional APIs and advanced features. You can find a comprehensive list of supported APIs on our ☑️ Feature Coverage page.

LocalStack also provides additional features to make your life as a cloud developer easier! Check out LocalStack's User Guides for more information.

Install

The quickest way to get started with LocalStack is by using the LocalStack CLI. It enables you to start and manage the LocalStack Docker container directly through your command line. Ensure that your machine has a functional docker environment installed before proceeding.

Brew (macOS or Linux with Homebrew)

Install the LocalStack CLI through our official LocalStack Brew Tap:

brew install localstack/tap/localstack-cli

Binary download (macOS, Linux, Windows)

If Brew is not installed on your machine, you can download the pre-built LocalStack CLI binary directly:

Visit localstack/localstack-cli and download the latest release for your platform.
Extract the downloaded archive to a directory included in your PATH variable:
- For macOS/Linux, use the command: sudo tar xvzf ~/Downloads/localstack-cli-*-darwin-*-onefile.tar.gz -C /usr/local/bin

PyPI (macOS, Linux, Windows)

LocalStack is developed using Python. To install the LocalStack CLI using pip, run the following command:

python3 -m pip install localstack

The localstack-cli installation enables you to run the Docker image containing the LocalStack runtime. To interact with the local AWS services, you need to install the awslocal CLI separately. For installation guidelines, refer to the awslocal documentation.

Important: Do not use sudo or run as root user. LocalStack must be installed and started entirely under a local non-root user. If you have problems with permissions in macOS High Sierra, install with pip install --user localstack

Quickstart

Start LocalStack inside a Docker container by running:

 % localstack start -d

     __                     _______ __             __
    / /   ____  _________ _/ / ___// /_____ ______/ /__
   / /   / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/
  / /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,<
 /_____/\____/\___/\__,_/_//____/\__/\__,_/\___/_/|_|

- LocalStack CLI: 4.9.0
- Profile: default
- App: https://app.localstack.cloud

[17:00:15] starting LocalStack in Docker mode 🐳               localstack.py:512
           preparing environment                               bootstrap.py:1322
           configuring container                               bootstrap.py:1330
           starting container                                  bootstrap.py:1340
[17:00:16] detaching                                           bootstrap.py:1344

You can query the status of respective services on LocalStack by running:

% localstack status services
┏━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┓
┃ Service                  ┃ Status      ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━┩
│ acm                      │ ✔ available │
│ apigateway               │ ✔ available │
│ cloudformation           │ ✔ available │
│ cloudwatch               │ ✔ available │
│ config                   │ ✔ available │
│ dynamodb                 │ ✔ available │
...

To use SQS, a fully managed distributed message queuing service, on LocalStack, run:

% awslocal sqs create-queue --queue-name sample-queue
{
    "QueueUrl": "http://sqs.us-east-1.localhost.localstack.cloud:4566/000000000000/sample-queue"
}

Learn more about LocalStack AWS services and using them with LocalStack's awslocal CLI.

Running

You can run LocalStack through the following options:

Usage

To start using LocalStack, check out our documentation.

To use LocalStack with a graphical user interface, you can use the following UI clients:

Releases

Please refer to GitHub releases to see the complete list of changes for each release. For extended release notes, please refer to the changelog.

Contributing

If you are interested in contributing to LocalStack:

Start by reading our contributing guide.
Check out our [development environment s

Localstack

Install / Use

README