Installation

Basic installation guide to get started with LocalStack on your local machine.

LocalStack CLI

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 environment 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 install the LocalStack CLI using Brew directly from our official LocalStack tap:
$ brew install localstack/tap/localstack-cli
Alternative: Binary Download

Alternatively, you can download the respective binary for your architecture directly:

or use this curl command:

$ curl -Lo localstack-cli-3.2.0-darwin-amd64-onefile.tar.gz \
    https://github.com/localstack/localstack-cli/releases/download/v3.2.0/localstack-cli-3.2.0-darwin-amd64-onefile.tar.gz

Then extract the LocalStack CLI from the terminal:

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

Alternative: Python You can also install the LocalStack CLI directly in your Python environment.
Please make sure to install the following tools on your machine before moving ahead:
  • python (Python 3.7 up to 3.11 is supported)
  • pip (Python package manager)

Afterwards you can install the LocalStack CLI in your Python environment with:

$ python3 -m pip install --upgrade localstack

You can download the respective binary for your architecture directly:

or use this curl command:

For x86-64:

$ curl -Lo localstack-cli-3.2.0-linux-amd64-onefile.tar.gz \
    https://github.com/localstack/localstack-cli/releases/download/v3.2.0/localstack-cli-3.2.0-linux-amd64-onefile.tar.gz

Or ARM64:

$ curl -Lo localstack-cli-3.2.0-linux-arm64-onefile.tar.gz \
    https://github.com/localstack/localstack-cli/releases/download/v3.2.0/localstack-cli-3.2.0-linux-arm64-onefile.tar.gz

Then extract the LocalStack CLI from the terminal:

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

Alternative: Homebrew on Linux Alternatively, 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
Alternative: Python You can also install the LocalStack CLI directly in your PYthon environment.
Please make sure to install the following tools on your machine before moving ahead:
  • python (Python 3.7 up to 3.11 is supported)
  • pip (Python package manager)

Afterwards you can install the LocalStack CLI in your Python environment with:

$ python3 -m pip install --upgrade localstack
You can download the respective binary for your architecture directly:
Then extract the archive and execute the binary using Powershell.
Alternative: Python You can also install the LocalStack CLI directly in your Python environment.
Please make sure to install the following tools on your machine before moving ahead:
  • python (Python 3.7 up to 3.11 is supported)
  • pip (Python package manager)

Afterwards you can install the LocalStack CLI in your Python environment with:

$ python3 -m pip install --upgrade localstack
If you cannot use one of our prebuilt binary releases of LocalStack, you can install the LocalStack CLI in a Python environment.
Please make sure to install the following tools on your machine before moving ahead:
  • python (Python 3.7 up to 3.11 is supported)
  • pip (Python package manager)

Afterwards you can install the LocalStack CLI in your Python environment with:

$ python3 -m pip install --upgrade localstack

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

$ localstack --version
3.2.0

You are all set! To use all of LocalStack’s features we recommend to get a LocalStack account and set up your auth token. Afterwards, check out our Quickstart guide to start your local cloud!

Alternatives

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. For a comprehensive overview of the LocalStack images, check out our Docker images documentation.

LocalStack Desktop

Download our desktop client at app.localstack.cloud/download. See LocalStack Desktop.

LocalStack Docker Extension

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

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

Starting LocalStack with Docker-Compose

You can start LocalStack with Docker Compose by configuring a docker-compose.yml file. Currently, docker-compose version 1.9.0+ is supported.

version: "3.8"

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"
version: "3.8"

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 Pro: 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

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 environment 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 4566:4566 \
  -p 4510-4559:4510-4559 \
  localstack/localstack
docker run \
  --rm -it \
  -p 4566:4566 \
  -p 4510-4559:4510-4559 \
  -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
  localstack/localstack-pro

Helm

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

Prerequisites

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.

Updating

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

Updating the LocalStack CLI itself (localstack update localstack-cli and localstack update all) is currently only supported if you installed the CLI in a Python environment. If you have installed the CLI with Brew or directly as a binary, please simply perform the installation commands again to update to the latest version.

Troubleshooting

  • The LocalStack CLI installation is successful, but I cannot execute localstack on my terminal.

    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

  • 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 shape 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 to discover issues?

    You can now share the LocalStack logs with us to help us discover issues. To share the logs, run our 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. If this does not solve your problem then please reach out for help and support.

What’s next?

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


Last modified December 15, 2023: Refine docker compose yml (#963) (ec792ca41)