Installation

LocalStack provides multiple installation paths depending on your development environment and requirements. We recommend using a CLI-based installation for the most consistent local development experience.

Choose the CLI that fits your workflow: use lstk for a streamlined, non-Python setup, or LocalStack CLI for access to our complete feature set.

lstk

lstk is a lightweight, Go-based binary that manages the authentication and container lifecycle in a single workflow.

Early Release

lstk currently supports core lifecycle commands: start, stop, logs, and status. For advanced features like Cloud Pods or Extensions, use the LocalStack CLI.

Install lstk

Homebrew

brew install localstack/tap/lstk

npm

npm install -g @localstack/lstk

Binary

Download the binary for your platform from the GitHub Releases and add it to your PATH.

Start LocalStack

lstk start

The first execution initiates a browser-based login flow. Subsequent starts use credentials stored in your system keyring.

LocalStack CLI

The LocalStack CLI is the primary tool for managing all LocalStack capabilities.

Requirement: You must have a working Docker installation before proceeding.

Install LocalStack CLI

Linux

You can download the pre-built binary for your architecture using the link below:

x86-64

ARM64

or use the curl commands below:

For x86-64:

curl --output localstack-cli-4.14.0-linux-amd64-onefile.tar.gz \
    --location https://github.com/localstack/localstack-cli/releases/download/v4.14.0/localstack-cli-4.14.0-linux-amd64-onefile.tar.gz

For ARM64:

curl --output localstack-cli-4.14.0-linux-arm64-onefile.tar.gz \
    --location https://github.com/localstack/localstack-cli/releases/download/v4.14.0/localstack-cli-4.14.0-linux-arm64-onefile.tar.gz

Then extract the LocalStack CLI from the terminal:

sudo tar xvzf localstack-cli-4.14.0-linux-*-onefile.tar.gz -C /usr/local/bin

Alternative: Homebrew on Linux

If you are using Homebrew for Linux, you can install the LocalStack CLI directly from our official LocalStack tap:

brew install localstack/tap/localstack-cli

MacOS

You can install the LocalStack CLI using Brew directly from our official LocalStack tap:

brew install localstack/tap/localstack-cli

Alternative: Binary Download

You may download the binary for your architecture using the link below:

Intel (AMD64)

or use the following curl command:

curl --output 4.14.0-darwin-amd64-onefile.tar.gz   --location https://github.com/localstack/localstack-cli/releases/download/4.14.0/localstack-cli-4.14.0-darwin-amd64-onefile.tar.gz

Then extract the LocalStack CLI from the terminal:

sudo tar xvzf localstack-cli-4.14.0-darwin-*-onefile.tar.gz -C /usr/local/bin

Windows

You can download the pre-built binary for your architecture using the link below:

Intel (AMD64)

Then extract the archive and execute the binary in Powershell.

Other/Python

If you cannot use the binary releases of LocalStack, you can install the Python distribution.

Please make sure to install the following before moving ahead:

• Python
• pip

Next install the LocalStack CLI in your Python environment by running:

python3 -m pip install --upgrade localstack

Note

To download a specific version of LocalStack, replace <version> with the required version from release page.

python3 -m pip install localstack==<version>

MacOS Sierra?

If you have problems with permissions in MacOS X Sierra, install with:

python3 -m pip install --user localstack

Danger

Do not use sudo or the root user when starting LocalStack. It should be installed and started entirely under a local non-root user.

Start LocalStack CLI

To verify that the LocalStack CLI was installed correctly, you can check the version in your terminal:

localstack --version
4.14.0

You are all set!

Note

To start LocalStack, you must first set up your auth token.

Once you’ve set up your auth token, you can start LocalStack with the following command:

localstack start # start localstack in background with -d flag

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

 💻 LocalStack CLI ${LOCALSTACK_VERSION}
 👤 Profile: default

[12:47:13] starting LocalStack in Docker mode 🐳                       localstack.py:494
           preparing environment                                       bootstrap.py:1240
           configuring container                                       bootstrap.py:1248
           starting container                                          bootstrap.py:1258
[12:47:15] detaching                                                   bootstrap.py:1262

Update LocalStack CLI

The LocalStack CLI allows you to easily update the different components of LocalStack. To check the various options available for updating, run:

localstack update --help

Usage: localstack update [OPTIONS] COMMAND [ARGS]...

  Update different LocalStack components.

Options:
  -h, --help  Show this message and exit.

Commands:
  all             Update all LocalStack components
  docker-images   Update docker images LocalStack depends on
  localstack-cli  Update LocalStack CLI

Note

Updating the LocalStack CLI using localstack update localstack-cli and localstack update all will work only if it was installed from the Python distribution. If it was installed using the pre-built binary or via Brew, please run the installation steps again to update to the latest version.

Container & Orchestration Methods

Use these methods for CI pipelines, server environments, or manual container management.

Docker Compose

Recommended for CI and team environments. Create a docker-compose.yml with the following configuration:

services:
  localstack:
    container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}"
    image: localstack/localstack-pro
    ports:
      - "127.0.0.1:4566:4566"            # Gateway
      - "127.0.0.1:4510-4559:4510-4559"  # External service range
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
      - PERSISTENCE=${PERSISTENCE:-0}
    volumes:
      - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack"
      - "/var/run/docker.sock:/var/run/docker.sock"

Execute docker compose up to start.

Docker CLI

Run the container directly via the Docker engine:

docker run \
  --rm -it \
  -p 127.0.0.1:4566:4566 \
  -p 127.0.0.1:4510-4559:4510-4559 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
  localstack/localstack-pro

Helm (Kubernetes)

Deploy LocalStack to a Kubernetes cluster:

helm repo add localstack-repo [https://helm.localstack.cloud](https://helm.localstack.cloud)
helm upgrade --install localstack localstack-repo/localstack

Graphical User Interfaces (GUIs)

LocalStack Desktop

Manage local instances via a standalone desktop application. Download here.

Docker Desktop Extension

Install the official extension to manage LocalStack directly from the Docker Desktop dashboard.

Troubleshooting

The LocalStack CLI installation is successful, but I cannot execute localstack

If you can successfully install LocalStack using pip but you cannot use it in your terminal, you most likely haven’t set up your operating system’s / terminal’s PATH variable (in order to tell them where to find programs installed via pip).

• If you are using Windows, you can enable the PATH configuration when installing Python, as described in the official docs of Python.
• If you are using a MacOS or Linux operating system, please make sure that the PATH is correctly set up - either system wide, or in your terminal.

As a workaround you can call the LocalStack CLI python module directly:

python3 -m localstack.cli.main

The localstack CLI does not start the LocalStack container

If you are using the localstack CLI to start LocalStack, but the container is not starting, please check the following:

• Uncheck the Use kernel networking for UDP option in Docker Desktop (Settings → Resources → Network) or follow the steps in our documentation to disable it.
• Start LocalStack with a specific DNS address:

DNS_ADDRESS=0 localstack start

• Remove port 53 as indicated in our standard docker-compose.yml file.

How should I access the LocalStack logs on my local machine?

You can now avail logging output and error reporting using LocalStack logs. To access the logs, run the following command:

localstack logs

AWS requests are now logged uniformly in the INFO log level (set by default or when DEBUG=0). The format is:

AWS <service>.<operation> => <http-status> (<error type>)

Requests to HTTP endpoints are logged in a similar way:

2022-09-12T10:39:21.165  INFO --- [   asgi_gw_0] localstack.request.aws     : AWS s3.ListBuckets => 200
2022-09-12T10:39:41.315  INFO --- [   asgi_gw_0] localstack.request.aws     : AWS s3.CreateBucket => 200
2022-09-12T10:40:04.662  INFO --- [   asgi_gw_0] localstack.request.aws     : AWS s3.PutObject => 200
2022-09-12T11:01:55.799  INFO --- [   asgi_gw_0] localstack.request.http    : GET / => 200

How should I share the LocalStack logs for troubleshooting?

You can share the LocalStack logs with us to help us identify issues. To share the logs, call the diagnostic endpoint:

curl -s localhost:4566/_localstack/diagnose | gzip -cf > diagnose.json.gz

Ensure that the diagnostic endpoint is run after you have tried reproducing the affected task. After running the task, run the diagnostic endpoint and share the archive file with your team members or LocalStack Support.

My application cannot reach LocalStack over the network

We have extensive network troubleshooting documentation available here.

If this does not solve your problem then please reach out to LocalStack Support.

Next steps

Now that you’ve completed installation, proceed to the Local Development Guide to start LocalStack and deploy a serverless API. This guide walks you through deploying a Lambda function backed by a DynamoDB table entirely on your local machine.