Skip to main content
Multi-Arch Docker Builds with Buildx: One Image, Every Platform

Multi-Arch Docker Builds with Buildx: One Image, Every Platform

KU
· Founder & Chief Editor
• 7 min read•Updated •65 views

Our M-series laptops built arm64, our CI built amd64, and prod pulled whichever tag won the race. Buildx and a manifest list ended the chaos.

Key takeaways

  • Run docker buildx build --platform linux/amd64,linux/arm64 --push to publish one tag backed by a manifest list, so every node pulls the architecture it needs.
  • Add registry cache with mode=max.
  • If QEMU emulation is too slow, build each architecture on a native runner and merge the results with docker buildx imagetools create.

Build one tag for both architectures with docker buildx build --platform linux/amd64,linux/arm64 --tag registry/app:1.8.3 --push .. Buildx produces a manifest list, and each machine pulls the image matching its own CPU. Add registry cache, and switch to native runners plus docker buildx imagetools create when QEMU emulation gets too slow.

Verified against

Docker Buildx v0.38.1 and Docker Engine 29 (containerd image store by default), against the docs.docker.com multi-platform build, registry cache and imagetools create reference pages, plus the GitHub-hosted runners reference. Checked October 2026.

The bug report said "works on my machine, crashes in prod." It really did. A developer on an M3 MacBook built and pushed app:latest, which was an arm64 image. Prod ran on amd64 EC2. The container refused to start with exec format error, which is Docker's way of saying you pushed the wrong architecture (the exec format error fix covers the diagnosis). We'd been lucky for months because CI usually pushed the amd64 build last and overwrote the laptop's. That afternoon the ordering flipped.

The fix is a single image tag that contains both architectures. No more races.

What a manifest list actually is

A normal image tag points at one image for one architecture. A manifest list (the OCI spec calls it an image index) is a small pointer object that says "for linux/amd64 use this digest, for linux/arm64 use that digest." When any Docker or Kubernetes node pulls the tag, the registry hands it the entry matching its own platform. The user does nothing. This is why official images like alpine run everywhere without you thinking about it: they are manifest lists under the hood.

Building it

Docker's docs say multi-platform images "require an image store that supports manifest lists." Docker Desktop and Docker Engine 29.0+ use the containerd image store by default, so a plain docker buildx build --platform ... works there. On older engines, or in CI where you want an isolated builder, create one with the docker-container driver:

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

Then build both platforms and push in a single command. With the docker-container driver the result is not loaded into your local image store, so --push is how it reaches anywhere useful:

Bash
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --tag registry.acme.io/app:1.8.3 \
    --push \
    .

On a standalone Linux engine, install the QEMU emulators first with docker run --privileged --rm tonistiigi/binfmt --install all; Docker Desktop ships them. Buildx then emulates the non-native architecture, which is transparent but slow. Docker's own docs warn that emulation can be much slower for compute-heavy work. For a Go service that compiles fast, it barely mattered to us. For a Python image where pip install compiled native extensions under emulation, builds went from a minute or two to several times that. If that hurts, read the native-runner section below.

There's a third option for compiled languages: cross-compilation. Pin the build stage with FROM --platform=$BUILDPLATFORM, then set GOOS and GOARCH from the automatic TARGETOS and TARGETARCH build args. The compiler runs natively and only the output targets arm64, so QEMU never runs.

Caching, or your CI bill explodes

Without a cache, every build recompiles everything for both architectures. Use registry-backed cache so cache survives across ephemeral CI runners.

Bash
docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --cache-from type=registry,ref=registry.acme.io/app:buildcache \
    --cache-to type=registry,ref=registry.acme.io/app:buildcache,mode=max \
    --tag registry.acme.io/app:1.8.3 \
    --push \
    .

The default mode=min exports only the final stage's layers. mode=max caches every stage of a multi-stage Dockerfile, which is what you want when the expensive work happens in a builder stage. On warm-cache runs most of our build time disappeared even with arm64 emulation, because unchanged layers came straight from the registry. If cache hits still miss, the Docker build cache fix walks through the usual layer-ordering mistakes.

When emulation is too slow: native runners

For the Python case, QEMU was unacceptable. The clean answer is building each architecture on native hardware and stitching the results into one manifest afterward. GitHub-hosted Linux arm64 runners (ubuntu-24.04-arm, among others) are available for public and private repositories as of October 2026, so you build amd64 on an amd64 runner, arm64 on an arm64 runner, push each with a per-arch suffix, then create the manifest list in a final job.

Bash
# on each native runner, push a per-arch tag
docker buildx build --platform linux/amd64 \
    --tag registry.acme.io/app:1.8.3-amd64 --push .

# in a final job, combine into one multi-arch tag
docker buildx imagetools create \
    --tag registry.acme.io/app:1.8.3 \
    registry.acme.io/app:1.8.3-amd64 \
    registry.acme.io/app:1.8.3-arm64

imagetools create builds a new manifest list from source manifests that already exist in the registry, without rebuilding anything, so the combine step is quick. Our native arm64 build of the Python image ended up roughly as fast as the amd64 one, and the two run in parallel. The per-arch tags stick around afterward; prune them with your registry's retention policy if they clutter the UI.

Verifying you actually shipped both

Trust nothing. Inspect the pushed tag and confirm both platforms are present before you call it done.

Bash
docker buildx imagetools inspect registry.acme.io/app:1.8.3

You want to see two Platform: entries, linux/amd64 and linux/arm64. We added this as a CI assertion that greps the output and fails the pipeline if either architecture is missing, because a silently single-arch image is the exact bug we were trying to kill. If you build in GitHub Actions, the same checks slot into the workflow in building and pushing Docker images with GitHub Actions.

Where this breaks

Emulation is not perfect: some syscalls and JIT-heavy runtimes misbehave under QEMU, which is when native nodes stop being optional. Base images must themselves be multi-arch; a FROM image that only publishes amd64 fails the arm64 leg. And loading a multi-platform result into a local engine needs an image store that supports manifest lists, so older engines without the containerd store still need --push.

Questions people ask

Do I need --push for a multi-platform build?

Only if your builder can't store manifest lists locally. Docker Desktop and Docker Engine 29.0+ use the containerd image store by default, which holds multi-platform images, so you can build and keep them locally. Builds on the docker-container driver are not loaded into the engine's image store, so you push them to a registry with --push. In CI that's almost always what you want anyway.

Why is my arm64 build so slow on an amd64 runner?

Buildx runs the arm64 stages under QEMU emulation, and every instruction is translated. Steps that compile code, such as pip install building C extensions or npm native modules, suffer most. Three fixes, in order of effort: cache with mode=max so unchanged layers are skipped, cross-compile using $BUILDPLATFORM and TARGETARCH, or build on a native arm64 runner and merge with imagetools create.

How do I check which architectures an image tag supports?

Run docker buildx imagetools inspect <image>:<tag>. For a multi-arch tag the output lists the manifest list plus one entry per platform, each with its own digest and a Platform: line such as linux/arm64. A single-arch image shows only one manifest. Grep that output in CI and fail the pipeline if an expected platform is missing.

The call we'd make

For fast-compiling languages like Go or Rust, use the simple one-command buildx build with --platform linux/amd64,linux/arm64 and registry cache, or cross-compile and skip emulation entirely. The pipeline stays a single job. For anything that compiles native extensions during the build (Python with C deps, some Node modules), spend the extra pipeline complexity on native runners plus imagetools create, because QEMU will otherwise multiply your build time. Either way, add the imagetools inspect check so a single-arch image can never sneak to prod again.

Sources

Explore topics:DockerCI/CDDevOps
React
Share this post
Cite this article
Plain text

Kiril Urbonas (2026). Multi-Arch Docker Builds with Buildx: One Image, Every Platform. DevOpsNess. Updated 2026-10-31. https://www.devopsness.com/blog/multi-arch-docker-builds-with-buildx

Markdown

[Multi-Arch Docker Builds with Buildx: One Image, Every Platform](https://www.devopsness.com/blog/multi-arch-docker-builds-with-buildx) (Kiril Urbonas, DevOpsNess, updated 2026-10-31)

KU

Kiril Urbonas

Founder & Chief Editor

604 articles
View all articles by Kiril Urbonas

You might have missed

Evergreen posts worth revisiting.