Installation

Introduction

You can set up the Azure emulator by utilizing LocalStack for Azure Docker image. Before starting, ensure you have a valid LOCALSTACK_AUTH_TOKEN to access the Azure emulator. Refer to the Auth Token guide to obtain your Auth Token and specify it in the LOCALSTACK_AUTH_TOKEN environment variable.

The Azure Docker image is available on the LocalStack Docker Hub. To pull the Azure Docker image, execute the following command:

$ docker pull localstack/localstack-azure-alpha

You can start the Azure emulator using the following methods:

1. localstack CLI
2. docker CLI
3. Docker Compose

localstack CLI

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

$ export LOCALSTACK_AUTH_TOKEN=<your_auth_token>
$ IMAGE_NAME=localstack/localstack-azure-alpha localstack start

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

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

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 / stable	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
nightly	Scheduled nightly builds	CI pipelines that need a fresh build on a regular cadence
YYYY.MM.patch (e.g. 2026.05.0)	Never (pinned)	Fully reproducible environments where no changes are acceptable

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.