Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 111 ยท Dockerfiles

Multi-Platform Images

Build one Docker image that runs on amd64 and arm64: buildx --platform, manifest lists, QEMU emulation, cross-compiling stages and Apple Silicon pitfalls.

A container shares the kernel of its host, and a kernel runs programs for exactly one CPU architecture. A binary compiled for Intel and AMD chips (amd64, also called x86-64) cannot run on an Apple Silicon Mac or an AWS Graviton server, which use arm64 (also called aarch64). Since both kinds of machines are everywhere, an image published for only one of them will, at best, run slowly under emulation and, at worst, refuse to start.

The fix is a multi-platform image: one image name that quietly resolves to the right variant for whoever pulls it. This lesson explains how that works, how to build such images with docker buildx, how emulation and cross-compilation differ, and which pitfalls bite people on Apple Silicon. Outputs come from a real amd64 Windows machine running Docker Desktop with Docker Engine 29.8, which can build and run arm64 images.

One name, several images: manifest lists

When you pull alpine:3.22, the registry does not hand you one image. It returns a small JSON document called an image index (older documents call it a manifest list), which maps platforms to concrete images. Your Docker client picks the entry that matches your machine.

TEXT
alpine:3.22  (image index)
 โ”œโ”€โ”€ linux/amd64   -> image A (layers for Intel/AMD)
 โ”œโ”€โ”€ linux/arm64   -> image B (layers for Arm)
 โ”œโ”€โ”€ linux/arm/v7  -> image C
 โ””โ”€โ”€ linux/riscv64 -> image D ...

Inspect one without pulling:

CONSOLE
$ docker buildx imagetools inspect alpine:3.22
Name:      docker.io/library/alpine:3.22
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:2e0b81d60597f449baa56dc25d355367869d2dca4cd57e866f1e2b52af3eb55f

Manifests:
  Name:        docker.io/library/alpine:3.22@sha256:dc92f017beea...
  MediaType:   application/vnd.oci.image.manifest.v1+json
  Platform:    linux/amd64
  ...

The digest at the top identifies the index. Every entry below has its own digest, its own layers and its own platform. A platform is written os/architecture[/variant], for example linux/amd64, linux/arm64 or linux/arm/v7.

You can ask which platforms are available with a Go-template format:

CONSOLE
$ docker buildx imagetools inspect alpine:3.22 --format '{{range .Manifest.Manifests}}{{.Platform.OS}}/{{.Platform.Architecture}} {{end}}'
linux/amd64 unknown/unknown linux/arm/v6 unknown/unknown linux/arm/v7 unknown/unknown linux/arm64 ...

Those unknown/unknown entries are not real platforms. They are attestations (provenance and SBOM documents) stored next to each image. Ignore them when counting platforms.

Which platform do I have, and which did I get?

CONSOLE
$ docker run --rm alpine:3.22 uname -m
x86_64
$ docker run --rm --platform linux/arm64 alpine:3.22 uname -m
aarch64

The second command ran an Arm image on an Intel machine and printed aarch64. --platform tells Docker which variant to select (and pull if needed). To see what an image on your machine is, inspect it:

CONSOLE
$ docker image inspect tcd-armonly --format '{{.Os}}/{{.Architecture}}'
linux/arm64

When an image exists for a different platform than your host and you did not request one explicitly, Docker still runs it but warns you:

CONSOLE
$ docker run --rm tcd-armonly
WARNING: The requested image's platform (linux/arm64) does not match the detected host platform (linux/amd64/v3) and no specific platform was requested
building on linux/amd64 for linux/arm64 (arch arm64)
aarch64

That warning is the most common sign of an Apple Silicon problem in reverse: someone built an image for the wrong architecture and pushed it as the only variant.

Emulation: running foreign programs with QEMU

How did an Intel CPU run an Arm program? Through emulation. Linux has a feature called binfmt_misc that lets the kernel hand an unknown executable format to a helper program. Docker Desktop ships the QEMU user-mode emulator registered for all common architectures, so foreign binaries "just work" and your builder reports many platforms:

CONSOLE
$ docker buildx inspect | grep Platforms
Platforms:        linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/arm/v7, linux/arm/v6

Emulation has a price. I timed a small shell loop (300,000 additions) in a fresh Alpine container, native and emulated:

CONSOLE
$ time docker run --rm --platform linux/amd64 alpine:3.22 sh -c 'i=0; while [ $i -lt 300000 ]; do i=$((i+1)); done; echo $i'
300000
real	0m3.293s
$ time docker run --rm --platform linux/arm64 alpine:3.22 sh -c 'i=0; while [ $i -lt 300000 ]; do i=$((i+1)); done; echo $i'
300000
real	0m15.053s

On this machine the emulated run took about five times as long (container start-up included in both numbers). Compilers, package installs and test suites under QEMU are often painfully slow, and some programs that use special CPU instructions or JIT compilers crash. Treat emulation as a convenience for light work, not as the way to build production images.

On Linux with plain Docker Engine, the emulators are not always installed. The usual one-time setup is to run the tonistiivi/binfmt helper image with --install all. That container needs --privileged, so this is a read-only example here and something to do only on machines you control. Docker Desktop (Windows, macOS) and recent distributions with qemu-user-static already have it. Without emulation, running a foreign image fails with exec format error.

Building for several platforms with buildx

docker buildx build --platform takes a comma-separated list and produces one image per platform, combined into an index. Here is a Dockerfile that records where it was built and for what:

DOCKERFILE
FROM alpine:3.22
ARG TARGETPLATFORM
ARG TARGETARCH
ARG BUILDPLATFORM
RUN echo "building on $BUILDPLATFORM for $TARGETPLATFORM (arch $TARGETARCH)" > /info.txt && uname -m >> /info.txt
CMD ["cat", "/info.txt"]

Multi-platform results are usually pushed straight to a registry, because the classic image store could hold only one platform per tag. I used a throwaway local registry (registry:2) on 127.0.0.1:18930; with a real registry only the name changes:

CONSOLE
$ docker buildx build --platform linux/amd64,linux/arm64 \
    -t 127.0.0.1:18930/tcd-mp:1 --push --progress=plain .
#5 [linux/amd64 1/2] FROM docker.io/library/alpine:3.22@sha256:2e0b81d6...
#6 [linux/arm64 1/2] FROM docker.io/library/alpine:3.22@sha256:2e0b81d6...
#7 [linux/arm64 2/2] RUN echo "building on linux/amd64 for linux/arm64 (arch arm64)" > /info.txt && uname -m >> /info.txt
#8 [linux/amd64 2/2] RUN echo "building on linux/amd64 for linux/amd64 (arch amd64)" > /info.txt && uname -m >> /info.txt
#9 pushing manifest for 127.0.0.1:18930/tcd-mp:1@sha256:b520a2a0...

Each step appears once per platform, tagged [linux/arm64 ...] or [linux/amd64 ...]. The arm64 build step ran under emulation, which is why uname -m said aarch64 even though the build host is Intel. Check the pushed result:

CONSOLE
$ docker buildx imagetools inspect 127.0.0.1:18930/tcd-mp:1
Name:      127.0.0.1:18930/tcd-mp:1
MediaType: application/vnd.oci.image.index.v1+json
Digest:    sha256:b520a2a018d3...

Manifests:
  Name:        127.0.0.1:18930/tcd-mp:1@sha256:69ef86d0920e...
  Platform:    linux/amd64

  Name:        127.0.0.1:18930/tcd-mp:1@sha256:ba2219a94fe0...
  Platform:    linux/arm64

  Name:        127.0.0.1:18930/tcd-mp:1@sha256:b029eefc129a...
  Platform:    unknown/unknown
  ...

Two real platforms plus attestation entries (BuildKit adds provenance information by default when you push). Now pull it on any machine; Docker chooses:

CONSOLE
$ docker run --rm 127.0.0.1:18930/tcd-mp:1
building on linux/amd64 for linux/amd64 (arch amd64)
x86_64
$ docker run --rm --platform linux/arm64 127.0.0.1:18930/tcd-mp:1
building on linux/amd64 for linux/arm64 (arch arm64)
aarch64

The same name ran as amd64 by default and as arm64 on request. That is exactly what your users experience on different hardware.

Loading multi-platform images locally

With Docker 29 and the default containerd image store, --load can keep several platforms of one tag in your local store, so you do not need a registry just to test:

CONSOLE
$ docker buildx build --platform linux/amd64,linux/arm64 -t tcd-go:multi --load .
$ docker run --rm --platform linux/arm64 tcd-go:multi
hello from linux/arm64
$ docker run --rm --platform linux/amd64 tcd-go:multi
hello from linux/amd64

(Older setups using the classic store refuse this and require --push or a single --platform.) You can see which store you use with docker info; mine reports the driver type io.containerd.snapshotter.v1.

Build variables for platform-aware Dockerfiles

BuildKit gives every build these predefined arguments. Declare them with a bare ARG in a stage before reading them.

Argument Meaning Example
BUILDPLATFORM Platform of the machine running the build linux/amd64
TARGETPLATFORM Platform you are building for linux/arm64
TARGETOS, TARGETARCH, TARGETVARIANT Parts of the target linux, arm64, v8
BUILDOS, BUILDARCH, BUILDVARIANT Parts of the build platform linux, amd64

Cross-compiling: fast builds without emulation

For compiled languages there is a much faster approach than running the compiler under QEMU: run the compiler natively and tell it to produce code for the target. Go makes this trivial; Rust, .NET and Java (bytecode is portable) work similarly. In the Dockerfile, pin the build stage to the builder's own platform with FROM --platform=$BUILDPLATFORM, and pass the target to the compiler:

DOCKERFILE
FROM --platform=$BUILDPLATFORM golang:alpine AS build
ARG TARGETOS
ARG TARGETARCH
WORKDIR /src
COPY go.mod main.go ./
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/hello .

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

The program prints runtime.GOOS and runtime.GOARCH. Build for both platforms:

CONSOLE
$ docker buildx build --platform linux/amd64,linux/arm64 -t tcd-go:multi --load --progress=plain .
#9  [linux/amd64 build 1/4] FROM docker.io/library/golang:alpine@sha256:b8c9b82a...
#12 [linux/amd64 build 4/4] RUN CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o /out/hello .
#13 [linux/amd64->arm64 build 4/4] RUN CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o /out/hello .
$ docker image ls tcd-go
IMAGE             ID             DISK USAGE   CONTENT SIZE   EXTRA
tcd-go:multi      d2054c6c5509         22MB         10.7MB

Read the step labels: [linux/amd64 build 4/4] is a native amd64 compile; [linux/amd64->arm64 build 4/4] means "running on amd64, producing arm64". Only one Go toolchain image (the amd64 one) was downloaded, and nothing was emulated during compilation. Only the final stage, which just copies a file, is per-platform. The multi-stage structure from Multi-Stage Builds makes this possible.

Cross-compiling works when the compiler can target the other architecture and you have no native libraries to build. With CGO_ENABLED=1, Python packages with C extensions, or Node native modules, you generally need either a real cross toolchain or an honest build on matching hardware.

Apple Silicon and Graviton pitfalls

  1. An amd64-only image on an Arm Mac. Docker runs it under emulation (Rosetta or QEMU, depending on your Docker Desktop settings): slower, more memory, occasional crashes. The warning above appears. If the image has an arm64 variant, prefer it; if not, ask the maintainer or build it yourself.
  2. Building on an Arm Mac and deploying to an amd64 server. You build an arm64 image, push it, and the server answers exec format error. The fix is to build with --platform linux/amd64 (or both platforms) on the machine that builds the release, ideally in CI.
  3. Forcing a platform in Compose. A service can request an emulated platform with platform: linux/amd64. Use it as a temporary workaround for an image without an arm64 build, not as a permanent setting.
  4. Base images differ. Check that every FROM has the variants you need (docker buildx imagetools inspect tells you). One amd64-only base makes the whole multi-platform build fail or run under emulation.
  5. Scripts that download binaries. A curl .../tool-linux-amd64 in a Dockerfile builds fine on Arm and then fails at run time. Use $TARGETARCH to choose the right download.
DOCKERFILE
FROM alpine:3.22
ARG TARGETARCH
RUN echo "I would download tool-linux-${TARGETARCH}"

For Python or Node apps with no compiled parts, one Dockerfile usually builds multi-platform with no changes at all; the wheels and packages are fetched per architecture. For the full list of commands to inspect and run platforms, see the Docker cheat sheet and the CI side in Docker in CI.

Quick decision guide

Situation Approach
Pure scripts (Python, Node, PHP), no native extensions --platform linux/amd64,linux/arm64; emulation cost is small
Go, Rust, .NET Cross-compile with FROM --platform=$BUILDPLATFORM
Heavy C/C++ or native extensions Build each platform on native hardware (separate runners), then combine the manifests
Only developers on Arm, production on amd64 Build the release image for amd64 in CI; use emulation locally only to test
Quick local test of a foreign image docker run --platform ...

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does a registry return when you pull a multi-platform tag such as alpine:3.22?

    The tag points to an image index (manifest list). Each platform has its own manifest and layers, and the client selects the matching entry.
  2. 2. In docker buildx imagetools inspect output you see entries with Platform unknown/unknown. What are they?

    BuildKit stores attestations next to each image as extra manifests with an unknown platform. They are not runnable platforms.
  3. 3. Why is FROM --platform=$BUILDPLATFORM golang:alpine combined with GOARCH=$TARGETARCH faster than building arm64 under QEMU?

    The build stage runs on the builder's own architecture and cross-compiles. Only the final stage, which just copies the binary, is created for each target platform.
  4. 4. You build an image on an Apple Silicon Mac with a plain docker build and push it. The amd64 server fails with exec format error. What happened?

    A default build targets the machine's own architecture. Build with --platform linux/amd64 (or both) for the server, ideally in CI.
  5. 5. Why do you need ARG TARGETARCH inside a stage before using $TARGETARCH in a RUN?

    BuildKit provides these values automatically, but like other ARGs they are only visible in the stage where you declare them.

Summary

  • A tag can point to an image index with one image per platform (linux/amd64, linux/arm64, ...); the client picks the match, and --platform overrides it.
  • Foreign images run under QEMU emulation: handy, but much slower (about five times in my loop test), and not always installed on plain Linux Engine.
  • docker buildx build --platform a,b --push builds all variants; with the containerd image store, --load keeps them locally too.
  • BUILDPLATFORM, TARGETPLATFORM, TARGETOS, TARGETARCH let one Dockerfile adapt; declare them with ARG in the stage.
  • For compiled languages, cross-compile in a FROM --platform=$BUILDPLATFORM stage instead of emulating.
  • Watch for the warning about a platform mismatch, exec format error, amd64-only bases and hard-coded download URLs.

Next: Dockerfile Best Practices