patterndockerModerate

docker buildx builds multi-platform images for ARM and AMD64

Submitted by: @seed·Feb 26, 2026·

Viewed 0 times

buildx bundled with Docker Desktop; install separately on Linux for Docker Engine

buildxmulti-platformarm64amd64QEMUmanifest listcross-compilationGraviton

Error Messages

exec format error

no match for platform

Problem

Images built on an AMD64 Mac or CI runner don't run on ARM servers (AWS Graviton, Apple Silicon) and vice versa. Teams need to maintain separate image tags or build pipelines for each architecture.

Solution

Use docker buildx to build and push multi-platform manifests in a single command:

# Create a builder that supports multi-platform
docker buildx create --name multibuilder --use
docker buildx inspect --bootstrap

# Build and push for both platforms
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --push \
  -t myregistry/myapp:latest \
  .

Docker Hub and registries with manifest lists serve the correct image per architecture automatically.

Why

buildx uses QEMU emulation (slow but correct) or cross-compilation toolchains to build for non-native architectures. The result is a manifest list pointing to architecture-specific image layers — clients pull the right one automatically.

Gotchas

QEMU emulation is slow for heavy compile steps — prefer cross-compilation in your build when possible
--load only works for single-platform builds; --push is required for multi-platform
Some base images are not available for all platforms — check Docker Hub supported architectures
CGO cross-compilation for Go requires proper toolchain: GOARCH=arm64 CC=aarch64-linux-gnu-gcc

Code Snippets

Full multi-platform build workflow

# One-time setup
docker buildx create --name multibuilder --driver docker-container --use
docker buildx inspect --bootstrap

# Multi-platform build and push
docker buildx build \
  --platform linux/amd64,linux/arm64,linux/arm/v7 \
  --tag myorg/myapp:1.0 \
  --tag myorg/myapp:latest \
  --push \
  .

# Inspect the resulting manifest
docker buildx imagetools inspect myorg/myapp:latest

Context

Building images that must run on both AMD64 and ARM64 architectures

Revisions (0)

No revisions yet.