Building Multi-Architecture Images with Docker Buildx

Docker Buildx enables building container images for multiple CPU architectures (AMD64, ARM64, ARMv7) from a single build command. This is essential for supporting diverse deployment targets — cloud servers, Raspberry Pi, Apple Silicon Macs, and AWS Graviton instances. This guide covers setting up Buildx and creating multi-arch images.

Setup

# Buildx is included with Docker 19.03+
docker buildx version

# Create a new builder with multi-arch support
docker buildx create --name multiarch --driver docker-container --use --bootstrap

# List builders
docker buildx ls

# Install QEMU for cross-platform emulation
docker run --privileged --rm tonistiigi/binfmt --install all

Building Multi-Architecture Images

# Build for multiple platforms and push to registry
docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 \
    -t registry.example.com/myapp:latest \
    --push .

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

# Build and load locally (single platform only)
docker buildx build --platform linux/amd64 -t myapp:latest --load .

Dockerfile Best Practices for Multi-Arch

# Use official multi-arch base images
FROM --platform=$BUILDPLATFORM golang:1.22 AS builder

# Build arguments for target platform
ARG TARGETPLATFORM
ARG TARGETARCH
ARG TARGETOS

WORKDIR /app
COPY . .

# Cross-compile for the target architecture
RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -o /app/server .

# Final stage uses target platform automatically
FROM alpine:3.19
COPY --from=builder /app/server /usr/local/bin/server
CMD ["server"]

Node.js Multi-Arch

FROM --platform=$BUILDPLATFORM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
CMD ["node", "dist/index.js"]
# Node.js images are natively multi-arch — no special compilation needed

CI/CD Integration

# GitHub Actions
- name: Set up QEMU
  uses: docker/setup-qemu-action@v3

- name: Set up Docker Buildx
  uses: docker/setup-buildx-action@v3

- name: Build and push multi-arch
  uses: docker/build-push-action@v5
  with:
    platforms: linux/amd64,linux/arm64
    push: true
    tags: ghcr.io/user/myapp:latest
    cache-from: type=gha
    cache-to: type=gha,mode=max

Inspecting Multi-Arch Images

# View manifest list
docker manifest inspect registry.example.com/myapp:latest

# Shows platform-specific digests:
# linux/amd64: sha256:abc123...
# linux/arm64: sha256:def456...
# linux/arm/v7: sha256:ghi789...

# Docker automatically pulls the correct architecture for the host

Best Practices

• Use --platform=$BUILDPLATFORM in build stages for native compilation speed
• Use TARGETARCH and TARGETOS build args for cross-compilation
• Test images on actual target architectures, not just QEMU emulation
• Use BuildKit cache (type=gha or type=registry) for faster CI builds
• Always push multi-arch images to a registry — --load only supports single platform
• Start with amd64+arm64 — these cover 99% of deployment targets