Q: How do you build an image for multiple CPU architectures (AMD64 and ARM64)?
To build an image for multiple CPU architectures such as AMD64 and ARM64, use docker buildx build --platform linux/amd64,linux/arm64 --push.
Want to master this scenario in a live sandbox? KodeKloud's Docker Certified Associate (DCA) Hands-On Lab Course covers this exact problem with hands-on terminal drills.
🛠️ Production Runbook & Step-by-Step Resolution
Direct Answer: To <strong>build an image for multiple CPU architectures</strong> such as AMD64 and ARM64, use <code>docker buildx build --platform linux/amd64,linux/arm64 --push</code>. Buildx (BuildKit) produces one image per platform and publishes them under a single multi-platform manifest list, so each host pulls the matching variant automatically. Interviewers ask this because ARM servers and Apple Silicon laptops are common. They want to hear about emulation versus cross-compilation, base image support, and verifying the manifest.
Mental model: manifest list plus per-platform images
A tag like my-app:1.0 can point to an index that references several platform-specific images. Keep in mind that the build host and the target host may differ, which is the whole reason the platform flag exists.
- Manifest list (image index): maps platforms such as
linux/amd64andlinux/arm64to image digests. The runtime picks the right one. - Three build strategies: QEMU emulation (simple, slow), cross-compilation in one builder (fast, needs language support), and native builders per architecture (fastest, more setup).
- Base image must support every target: check that your
FROMimage publishes both platforms. - Local storage limit: with the classic image store the local daemon cannot hold a multi-platform image, so use
--pushor an OCI output. The containerd image store (optional in recent Docker releases) lifts this. - Why it matters: Apple Silicon laptops, AWS Graviton and other ARM nodes are common, and a single-architecture image forces developers to emulate or breaks deployment on mixed clusters.
Hands-on: build an image for multiple CPU architectures
Create a builder, enable emulation and push.
docker buildx create --name multi --driver docker-container --use
docker run --privileged --rm tonistiigi/binfmt --install arm64 # QEMU handlers
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t registry.example.com/my-app:1.0 \
--push .
# Local test of one architecture
docker buildx build --platform linux/arm64 -t my-app:arm --load .
- Create a builder: the default
dockerdriver cannot do multi-platform builds on the classic store, so use adocker-containerdriver builder. - Register QEMU: binfmt handlers let an AMD64 host run ARM64 binaries during the build.
- Build and push: authenticate to the registry first with
docker login. - Single platform load: to test locally use
--platform linux/arm64 --loadfor one architecture. - Tags and promotion: push one tag that resolves to the multi-platform index rather than separate
-amd64and-arm64tags, so Kubernetes and Compose files stay architecture-agnostic.
Make it fast: cross-compile instead of emulate
Running the compiler under QEMU can be many times slower. Let the build stage run natively and target the other platform.
# syntax=docker/dockerfile:1
FROM --platform=$BUILDPLATFORM golang:1.22 AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/app ./cmd/app
FROM gcr.io/distroless/static-debian12
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]
- Pin the build stage to the builder's platform:
FROM --platform=$BUILDPLATFORM. - Use automatic args: BuildKit sets
TARGETOS,TARGETARCHandBUILDPLATFORM. Declare them withARGto use them. - Final stage runs on target: copy the compiled binary into a small base image for each platform.
- Works best for Go, Rust and similar: interpreted stacks and native dependencies (Python wheels, Node addons) may need an emulated or native build.
- Pull behaviour: if a platform is missing from the index, the runtime reports
no matching manifest. This error is the signature of a build that only produced one architecture.
Verify the manifest and run each variant
A push succeeding does not prove both platforms work. Check each symptom against the evidence before changing anything.
- Inspect the index:
docker buildx imagetools inspect registry.example.com/my-app:1.0lists each platform and digest. - Run each platform:
docker run --rm --platform linux/arm64 registry.example.com/my-app:1.0 uname -mshould printaarch64. - Check emulated run speed: if tests pass only slowly under emulation, run them on real hardware before release.
- Common error:
exec format errormeans a binary for the wrong architecture ended up in the image, often from a missing--platformor a hard-coded download URL. - Testing strategy: run the unit tests natively and a smoke test per platform, since architecture-specific bugs such as alignment, SIMD code paths or native dependencies only surface on the real target.
Production practice: CI and native runners
Automate the build and keep it fast and secure.
- uses: docker/setup-qemu-action@v3
- uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v6
with:
platforms: linux/amd64,linux/arm64
push: true
tags: registry.example.com/my-app:1.0
cache-from: type=gha
cache-to: type=gha,mode=max
- GitHub Actions: use
docker/setup-qemu-action,docker/setup-buildx-action,docker/login-actionanddocker/build-push-actionwithplatforms: linux/amd64,linux/arm64. - Cache: use
cache-fromandcache-towithtype=ghaor a registry cache to avoid rebuilding every layer. - Native builders: for heavy builds, run one job per architecture on native runners and merge with
docker buildx imagetools create. - Supply chain: sign the index digest and attach SBOM and provenance attestations.
- Builder cleanup: remove stale builders with
docker buildx rm multiand prune the builder cache withdocker buildx pruneso build hosts do not accumulate gigabytes of layers.
- Multi-arch images are a manifest list pointing at per-platform images, and I build them with <code>docker buildx build --platform linux/amd64,linux/arm64 --push</code>.
- I verify with <code>buildx imagetools inspect</code> and run each variant to confirm <code>uname -m</code>, watching for <code>exec format error</code>.
- In CI I use setup-qemu and setup-buildx with a registry cache, or native runners per architecture for heavy builds.
Senior hiring managers and bar raisers evaluate how you prioritize during outages. Avoid these common anti-patterns:
- Building the whole toolchain under QEMU Emulated compilers are much slower. Cross-compile on the native build platform when the language supports it.
- Using a base image that lacks one platform The build fails or silently falls back. Check the base image's published platforms first.
- Hard-coding an AMD64 binary download in the Dockerfile The ARM64 image then contains an AMD64 binary and crashes with exec format error. Use TARGETARCH in the URL.
- Trying to --load a multi-platform build into the classic store It is not supported, so push to a registry or use an OCI output.