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

URL: https://www.devopsness.com/blog/multi-arch-docker-builds-with-buildx
Author: Kiril Urbonas
Published: 2026-07-01
Updated: 2026-10-31
Categories: DevOps
Tags: Docker, Containers, CI/CD, Build, DevOps

Summary: 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.

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

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]
> 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](/blog/fix-docker-exec-format-error) 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](/blog/fix-docker-build-cache) 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](/blog/github-actions-docker-build-push).

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

- [Docker Docs: Multi-platform builds](https://docs.docker.com/build/building/multi-platform/)
- [Docker Docs: Registry cache backend](https://docs.docker.com/build/cache/backends/registry/)
- [Docker Docs: docker buildx imagetools create](https://docs.docker.com/reference/cli/docker/buildx/imagetools/create/)
- [GitHub Docs: GitHub-hosted runners reference](https://docs.github.com/en/actions/reference/runners/github-hosted-runners)

