Skip to content

Installation

The quickest way get started with LocalStack is by using the LocalStack CLI. It allows you to start LocalStack from your command line. Please make sure that you have a working Docker installation on your machine before moving on.

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

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:

Terminal window
curl --output localstack-cli-4.6.0-linux-amd64-onefile.tar.gz \
--location https://github.com/localstack/localstack-cli/releases/download/v4.6.0/localstack-cli-4.6.0-linux-amd64-onefile.tar.gz

For ARM64:

Terminal window
curl --output localstack-cli-4.6.0-linux-arm64-onefile.tar.gz \
--location https://github.com/localstack/localstack-cli/releases/download/v4.6.0/localstack-cli-4.6.0-linux-arm64-onefile.tar.gz

Then extract the LocalStack CLI from the terminal:

Terminal window
sudo tar xvzf localstack-cli-4.6.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:

Terminal window
brew install localstack/tap/localstack-cli

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

Terminal window
localstack --version
4.6.0

You are all set!

You can now start LocalStack with the following command:

Terminal window
localstack start # start localstack in background with -d flag
Terminal window
__ _______ __ __
/ / ____ _________ _/ / ___// /_____ ______/ /__
/ / / __ \/ ___/ __ `/ /\__ \/ __/ __ `/ ___/ //_/
/ /___/ /_/ / /__/ /_/ / /___/ / /_/ /_/ / /__/ ,<
/_____/\____/\___/\__,_/_//____/\__/\__,_/\___/_/|_|
💻 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

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

Terminal window
localstack update --help
Terminal window
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

Besides using the CLI, there are other ways of starting and managing your LocalStack instance:

  • LocalStack Desktop
    Get a desktop experience and work with your local LocalStack instance via the UI.

  • LocalStack Docker Extension
    Use the LocalStack extension for Docker Desktop to work with your LocalStack instance.

  • Docker-Compose
    Use Docker Compose to configure and start your LocalStack Docker container.

  • Docker
    Use the Docker CLI to manually start the LocalStack Docker container.

  • Helm
    Use Helm to create a LocalStack deployment in a Kubernetes cluster.

LocalStack runs inside a Docker container, and the above options are different ways to start and manage the LocalStack Docker container.

The LocalStack emulator is available on Docker Hub in two editions: the Community Edition (localstack/localstack) and the Pro Edition (localstack/localstack-pro).

For a comprehensive overview of the LocalStack images, check out our Docker images documentation.

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

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

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.

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
ports:
- "127.0.0.1:4566:4566" # LocalStack Gateway
- "127.0.0.1:4510-4559:4510-4559" # external services port range
environment:
# LocalStack configuration: https://docs.localstack.cloud/references/configuration/
- DEBUG=${DEBUG:-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:

Terminal window
docker compose up

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:

Terminal window
localstack config validate

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.

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.

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

Terminal window
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 \
localstack/localstack

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

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

Terminal window
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.

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

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

Section titled “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:

Terminal window
python3 -m localstack.cli.main

The localstack CLI does not start the LocalStack container

Section titled “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 (SettingsResourcesNetwork) or follow the steps in our documentation to disable it.
  • Start LocalStack with a specific DNS address:
Terminal window
DNS_ADDRESS=0 localstack start

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

Section titled “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:

Terminal window
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?

Section titled “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:

Terminal window
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

Section titled “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.