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 the Azure emulator with minimal setup.

LocalStack for Azure 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.

Alternatively, you can set up the Azure emulator directly using the LocalStack for Azure Docker image, localstack/localstack-azure, with the docker CLI or Docker Compose.

lstk

lstk is a lightweight CLI for LocalStack that manages the authentication and container lifecycle for the AWS, Azure, and Snowflake emulators.

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 and, in an interactive terminal, prompts you to pick which emulator to run — choose z for Azure. Your choice is written to config.toml and used as the default on subsequent runs. Subsequent starts use credentials stored in your system keyring.

Update lstk

lstk update

For more details, see the lstk documentation.

Already using lstk with a different default emulator?

If your global config.toml already defaults to a different emulator (for example, AWS), target Azure for a specific project instead by creating a project-local .lstk/config.toml:

.lstk/config.toml

[[containers]]
type = "azure"
port = "4566"

Container and orchestration tools

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

docker CLI

To start the Azure emulator using the docker CLI, execute the following command:

$ docker run \
    --rm -it \
    -p 4566:4566 \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.localstack/volume:/var/lib/localstack \
    -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} \
    localstack/localstack-azure

Docker Compose

Create a docker-compose.yml file with the specified content:

version: "3.8"

services:
  localstack:
    container_name: "localstack-main"
    image: localstack/localstack-azure
    ports:
      - "127.0.0.1:4566:4566"
    environment:
      - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?}
    volumes:
      - "./volume:/var/lib/localstack"

Start the Azure emulator with the following command:

$ docker-compose up

Updating the Docker image

To update the Azure Docker container, pull the latest image and restart the container.

The following tags are available for the LocalStack for Azure Docker image:

Tag	Updated when	Recommended for
latest	Tagged releases only (e.g. 2026.05.0)	Most users, stable, release-quality builds
dev	Every merged commit on main	Users who need the latest unreleased changes

Starting with the end-of-March 2026 release, versioned Azure image tags follow calendar versioning in the YYYY.MM.patch format (for example, 2026.03.0). Refer to the available tags on Docker Hub for the latest releases.