Multi-Architecture Builds with Buildx

The plain-language idea

A Docker image isn't architecture-neutral — it contains compiled binaries and native dependencies built for one specific CPU architecture, most commonly amd64 (x86-64, the standard for most cloud VMs) or arm64 (Apple Silicon Macs, AWS Graviton instances, and other ARM-based cloud hardware chosen for its better price-to-performance ratio). An image built on one architecture doesn't run on the other — it either fails outright or silently runs under slow, best-effort emulation, depending on the host.

This mismatch is a completely ordinary thing to hit today: a developer on an Apple Silicon MacBook builds an image locally (arm64 by default), but the CI runner or production cluster is x86. Multi-architecture builds solve this by producing more than one image — one per target architecture — and publishing them under a single tag as a manifest list (also called an image index): a small piece of metadata that says "this tag actually points to several architecture-specific images; pick the one that matches you." docker pull myapp:latest on an x86 machine and an arm64 machine both work, and each transparently gets the right binary.

See it in a real thing: one command, two architectures, one tag

# Set up a buildx builder that supports multi-platform output (one-time setup)
docker buildx create --use

# Build and push both architectures under the same tag in one command
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t registry.example.com/myapp:latest \
  --push .

buildx is Docker's extended build command (built on BuildKit) that adds --platform — instead of building for whatever architecture the local machine happens to be, this single invocation produces an amd64 image, an arm64 image, and a manifest list tying both to myapp:latest, pushing all three to the registry in one step.

What people usually miss

Watch out

• A manifest list is not "the image" — it's a pointer to several images. docker pull and docker run resolve it automatically based on the local machine's architecture, but tools that inspect an image by digest sometimes need to be pointed at the specific architecture's digest inside the list, not the manifest list's own digest.
• --load and --push aren't interchangeable with --platform set to multiple architectures. --load puts a built image into the local Docker daemon so it can be run immediately, but a local daemon can only hold one architecture's image at a time — multi-platform output has nowhere local to "land," so it has to be --pushed straight to a registry instead.
• QEMU emulation isn't free, and it isn't infinite. Some native dependencies (particularly ones with architecture-specific compiled extensions) can fail to build under emulation even when the same source builds fine natively — a genuinely native build machine per architecture (a real arm64 CI runner, for instance) is the fix when emulation itself becomes the blocker, not just the slowdown.
• Architecture mismatch used to be a silent failure, not just a slow one. Before manifest lists were standard practice, pulling an amd64-only image onto an arm64 host would either refuse to run or (worse, on a host with some emulation layer already present) run under unexpected, unrequested emulation — multi-arch publishing is what removed that landmine, not just a convenience.

Why this matters in interviews

"Your team develops on M-series MacBooks but deploys to standard x86 cloud instances — how do you make sure the image you tested locally is actually the one that runs in production?" is a question this lesson answers precisely: buildx with --platform publishing both architectures under one tag, rather than "it just happens to work" or, worse, developers manually building on x86 hardware to match.