Installation

Introduction

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

Use lstk to install, authenticate, and start LocalStack with minimal setup.

LocalStack for AWS features require an Auth Token to activate your running instance. lstk handles authentication through a browser-based login flow, while Docker and CI workflows can use LOCALSTACK_AUTH_TOKEN.

lstk

lstk is a lightweight CLI for LocalStack that manages the authentication and container lifecycle in a single workflow.

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

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 lstk

lstk start

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

Update lstk

lstk update

For more details, see the lstk documentation.

Container and orchestration tools

Use these methods when you need explicit container configuration, want to run LocalStack alongside other services, or deploy LocalStack in CI and Kubernetes environments. For everyday local development, lstk is usually simpler.

Docker Compose

Use Docker Compose when you want a reusable configuration file that can be shared across a team or checked into a project repository. Create a docker-compose.yml with the following configuration:

services:
  localstack:
    container_name: '${LOCALSTACK_DOCKER_NAME:-localstack-main}'
    image: localstack/localstack
    ports:
      - '127.0.0.1:4566:4566' # LocalStack Gateway
      - '127.0.0.1:4510-4559:4510-4559' # external services port range
      - '127.0.0.1:443:443' # LocalStack HTTPS Gateway
    environment:
      # Activate LocalStack for AWS: https://docs.localstack.cloud/getting-started/auth-token/
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} # required for Pro
      # LocalStack configuration: https://docs.localstack.cloud/references/configuration/
      - DEBUG=${DEBUG:-0}
      - 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

Use the Docker CLI for one-off starts or when you want to test a container configuration before moving it into Compose:

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

Note

The Docker Compose and Docker CLI examples above use the same runtime settings:

• The 4566 port exposes the LocalStack Gateway.
• The 4510-4559 range exposes external service ports used by services that bind additional endpoints.
• The 443 port exposes the LocalStack HTTPS Gateway.
• The Docker socket mount is required for services that start additional containers, such as Lambda.
• Docker reuses a local image if one already exists. Pull explicitly or pin an image tag, such as localstack/localstack:<version>, when you need reproducible CI or team environments.
• If you use Docker bridge networking, container name resolution may not work as expected from other containers. Prefer the default LocalStack networking setup unless you have a specific reason to customize it.
• Configuration variables can be prefixed with LOCALSTACK_ in Docker. For instance, setting LOCALSTACK_PERSISTENCE=1 is equivalent to PERSISTENCE=1.

For more details, see the Docker images, configuration, and networking documentation.

Helm (Kubernetes)

Deploy LocalStack to a Kubernetes cluster:

helm repo add localstack-repo 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.

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

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:

lstk

lstk 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 Auth Token guide to activate LocalStack and prepare your environment for local development.