Multi-Platform Images

An image built on an Apple Silicon laptop is linux/arm64. Run it on a normal cloud VM and you get exec format error, or — worse, because it looks like it works — silent QEMU emulation at a fraction of the speed.

A multi-platform image is one tag that carries several architectures, with the registry handing each puller the right one.

What is actually stored

A multi-platform tag points at a manifest list (or "image index"): a small document listing one manifest per platform, each pointing at its own layers.

docker pull nginx:1.29-alpine on an ARM machine fetches the arm64 manifest and nothing else. The selection happens in the client, from the index, at pull time.

You need a different builder

The default docker driver builds one platform at a time. Multi-platform needs a builder that can hold several results:

docker buildx create --name multi --driver docker-container --use
docker buildx inspect --bootstrap

The drivers worth knowing:

docker-container is the one to reach for locally, and the catch is that it cannot load a multi-platform result into your local image store. Push it, or build one platform at a time with --load.

The three ways to build for another architecture

Emulation. Easiest, slowest. QEMU translates instructions so an arm64 build runs on an amd64 machine unchanged.

docker run --privileged --rm tonistiigi/binfmt --install all

docker buildx build --platform linux/amd64,linux/arm64 -t acme/app:1.0 --push .

No Dockerfile changes. Docker Desktop bundles QEMU already. But anything compute-heavy — compiling, running a test suite — gets very slow, often ten times or worse.

Cross-compilation. Fastest, and language-dependent. Build natively and target the other architecture, using the build arguments BuildKit provides:

# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.25-alpine AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY . .
RUN --mount=type=cache,target=/root/.cache/go-build \
    GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/server ./cmd/server

FROM alpine:3.22
COPY --from=build /out/server /usr/local/bin/server
ENTRYPOINT ["server"]

--platform=$BUILDPLATFORM pins the build stage to the builder's native architecture, so the compiler runs at full speed. $TARGETOS and $TARGETARCH say what to produce. The final stage has no --platform, so it is built for each target — it only copies a binary, which is free.

Go, Rust, .NET and anything else with a real cross-compiler suit this. Interpreted languages with native extensions usually do not.

Native nodes. Best of both, most setup: a builder with a real machine per architecture.

docker buildx create --name multi --node amd64 --platform linux/amd64
docker buildx create --append --name multi --node arm64 --platform linux/arm64

Each stage runs natively on the matching node. This is what Docker Build Cloud sells as a service.

Building and shipping it

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ghcr.io/acme/app:1.0 \
  --push .

--push matters. A multi-platform result cannot be loaded into the local image store by the docker-container driver, so --load fails and building without either output flag leaves you with nothing but a warmed cache.

Building only for your own machine while iterating:

docker buildx build --load -t app:dev .

Next up: Bake — the declarative file that replaces a page of buildx flags, and which Compose v5 now builds through.