Installation

Local development

There are two CLI options for running LocalStack on your laptop. Start with lstk if you want the fastest path to a running instance, or use the LocalStack CLI if you need full feature support.

lstk

lstk is a lightweight, Go-based CLI that handles the full startup sequence in one command: browser-based login, image pull, and container launch. It’s the fastest way to get LocalStack running locally.

Early release

lstk currently supports core lifecycle commands (start, stop, logs, status). For advanced features like Cloud Pods, Extensions, and Ephemeral Instances, use the LocalStack CLI instead. Both tools can coexist on the same system.

Install lstk:

Homebrew (macOS/Linux)

brew install localstack/tap/lstk

npm

npm install -g @localstack/lstk

Binary

Download a pre-built binary for your platform from GitHub Releases and add it to your PATH.

Start LocalStack:

lstk start

On first run, lstk opens a browser login flow. After authenticating, it pulls the LocalStack image and starts the container. Subsequent starts use the stored credential from your system keyring — no manual token management needed.

---

LocalStack CLI

The full-featured LocalStack CLI gives you access to all LocalStack capabilities. Please make sure that you have a working Docker installation on your machine before moving on.

Installing LocalStack CLI

The CLI starts and manages the LocalStack Docker container. For alternative methods of managing the LocalStack container, see our alternative installation instructions.

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.

Starting LocalStack

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

Updating 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.

CI and server environments

For CI pipelines and server deployments, you’ll manage the LocalStack container directly rather than using a local CLI. See the CI/CD Setup guide for a complete walkthrough including GitHub Actions examples.

The options below cover the main container management approaches:

• Docker Compose — recommended for CI and team environments
• Docker — direct container control for scripted setups
• Helm — deploy LocalStack in a Kubernetes cluster

The LocalStack emulator is available on Docker Hub as localstack/localstack-pro.

For a comprehensive overview of LocalStack images, see the Docker images documentation.

GUI tools

• LocalStack Desktop — desktop UI for managing your local instance
• LocalStack Docker Extension — manage LocalStack from Docker Desktop

LocalStack Desktop

Learn more about our desktop client at LocalStack Desktop and download it here.

LocalStack Docker Extension

Install our official Docker Desktop extension to manage LocalStack. See LocalStack Docker Extension for more information.

Docker-Compose

To use LocalStack without the LocalStack CLI, you have the option of running the LocalStack Docker container by yourself. If you want to manually manage your Docker container, it’s usually a good idea to use Docker Compose in order to simplify your container configuration.

Prerequisites

• Docker
• Docker Compose (version 1.9.0+)

Starting LocalStack with Docker-Compose

You can start LocalStack with Docker Compose by configuring a docker-compose.yml file. Docker Compose v1.9.0 and above is supported.

services:
  localstack:
    container_name: "${LOCALSTACK_DOCKER_NAME:-localstack-main}"
    image: localstack/localstack-pro  # required for Pro
    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 (Pro)
    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"

Start the container by running the following command:

docker compose up

Note

• This command pulls the current nightly build from the main branch (if you don’t have the image locally) and not the latest supported version. If you want to use a specific version, set the appropriate LocalStack image tag at services.localstack.image in the docker-compose.yml file (for example localstack/localstack:<version>).

• If you are using LocalStack with an Auth Token, you need to specify the image tag as localstack/localstack-pro in the docker-compose.yml file. Going forward, localstack/localstack-pro image will contain our Pro-supported services and APIs.

• This command reuses the image if it’s already on your machine, i.e. it will not pull the latest image automatically from Docker Hub.

• Mounting the Docker socket /var/run/docker.sock as a volume is required for some services that use Docker to provide the emulation, such as AWS Lambda. Check out the Lambda providers documentation for more information.

• To facilitate interoperability, configuration variables can be prefixed with LOCALSTACK_ in docker. For instance, setting LOCALSTACK_PERSISTENCE=1 is equivalent to PERSISTENCE=1.

• If using the Docker default bridge network using network_mode: bridge, container name resolution will not work inside your containers. Please consider removing it, if this functionality is needed.

• To configure an Auth Token, refer to the Auth Token documentation.

Please note that there are a few pitfalls when configuring your stack manually via docker-compose (e.g., required container name, Docker network, volume mounts, and environment variables). We recommend using the LocalStack CLI to validate your configuration, which will print warning messages in case it detects any potential misconfigurations:

localstack config validate

Docker

You can also directly start the LocalStack container using the Docker CLI instead of Docker-Compose. This method requires more manual steps and configuration, but it gives you more control over the container settings.

Prerequisites

Please make sure that you have a working Docker installation on your machine before moving on. You can check if Docker is correctly configured on your machine by executing docker info in your terminal. If it does not report an error (but shows information on your Docker system), you’re good to go.

Starting LocalStack with Docker

You can start the Docker container simply by executing the following docker run command:

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-pro

Note

• This command pulls the current nightly build from the main branch (if you don’t have the image locally) and not the latest supported version. If you want to use a specific version of LocalStack, use the appropriate tag: docker run --rm -it -p 4566:4566 -p 4510-4559:4510-4559 localstack/localstack:<tag>. Check-out the LocalStack releases to know more about specific LocalStack versions.

• If you are using LocalStack with an Auth Token, you need to specify the image tag as localstack/localstack-pro in your Docker setup. Going forward, localstack/localstack-pro image will contain our Pro-supported services and APIs.

• This command reuses the image if it’s already on your machine, i.e. it will not pull the latest image automatically from Docker Hub.

• Mounting the Docker socket /var/run/docker.sock as a volume is required for some services that use Docker to provide the emulation, such as AWS Lambda. Check out the Lambda providers documentation for more information.

• When using Docker to manually start LocalStack, you will have to configure the container on your own (see docker-compose-pro.yml and Configuration. This could be seen as the “expert mode” of starting LocalStack. If you are looking for a simpler method of starting LocalStack, please use the LocalStack CLI.

• To facilitate interoperability, configuration variables can be prefixed with LOCALSTACK_ in docker. For instance, setting LOCALSTACK_PERSISTENCE=1 is equivalent to PERSISTENCE=1.

• To configure an Auth Token, refer to the Auth Token documentation.

Helm

If you want to deploy LocalStack in your Kubernetes cluster, you can use Helm.

Prerequisites

• Kubernetes
• Helm

Deploy LocalStack using Helm

You can deploy LocalStack in a Kubernetes cluster by running these commands:

helm repo add localstack-repo https://helm.localstack.cloud
helm upgrade --install localstack localstack-repo/localstack

The Helm charts are not maintained in the main repository, but in a separate one.

What’s next?

Now that you have LocalStack up and running, the following resources might be useful for your next steps:

• Check out our Quickstart guide if you are a new user to get started with LocalStack quickly.
• Use the LocalStack integrations to interact with LocalStack and other integrated tools, for example:
  • Use awslocal to use the AWS CLI against your local cloud!
  • Use the Serverless Framework with LocalStack!
  • And many more!
• Find out how to configure LocalStack such that it perfectly fits your need.
• Use LocalStack in your CI environment to increase your code quality.
• Checkout LocalStack’s Cloud Developer Tools to further increase your development efficiency with LocalStack.
• Find out about the ways you can configure LocalStack.

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.