Installation

Introduction

You can set up the Azure emulator by utilizing LocalStack for Azure Docker image, localstack/localstack-azure. Before starting, ensure you have a valid Auth Token to access the Azure emulator; see the Auth Token guide to obtain one.

We recommend installing with lstk for the simplest setup — it handles authentication, image pulls, and the container lifecycle in a single workflow. Alternatively, you can start the Azure emulator directly 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.

Configure lstk for Azure

lstk starts the AWS emulator by default. To target the Azure emulator instead, create a project-local .lstk/config.toml:

.lstk/config.toml

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

Alternatively, run lstk interactively with no existing config file and choose z for Azure when prompted; your choice is written to config.toml automatically.

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