Stage 4 · Provision
Image Internals & Advanced Builds
Multi-Arch buildx
Publish amd64 and arm64 images with docker buildx, QEMU emulation, manifest lists, and platform testing.
Why Multi-Architecture?
Modern infrastructure runs on multiple CPU architectures. Apple Silicon (arm64) is now the default developer machine. Cloud providers offer arm64 instances for better price-performance. Building multi-arch images ensures your application runs natively on every platform.
| Architecture | Use Case | Performance |
|---|---|---|
| linux/amd64 | Intel/AMD servers, most cloud | Standard |
| linux/arm64 | Apple Silicon, AWS Graviton | Better price/performance |
| linux/arm/v7 | Raspberry Pi, IoT devices | Low power |
| linux/arm/v6 | Older ARM devices | Legacy |
buildx Setup
# Check if buildx is available
docker buildx version
# Create a new builder with multi-platform support
docker buildx create --name multiarch --driver docker-container --use
# Inspect the builder
docker buildx inspect --bootstrap
# Verify available platforms
docker buildx inspect --format '{{.Platforms}}'The docker-container driver creates a buildx builder running in a container. This driver supports QEMU emulation for cross-platform builds. The default docker driver does not support multi-platform builds.
Building for Multiple Platforms
# Build for multiple platforms and push
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t myregistry.com/myapp:1.0 \
--push .
# Build locally (creates manifest list but does not push)
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t myregistry.com/myapp:1.0 .
# Build for a specific platform
docker buildx build \
--platform linux/arm64 \
-t myregistry.com/myapp:arm64 \
--push .The --platform flag specifies target architectures. --push pushes to the registry after building. The registry receives a manifest list containing both platform-specific images.
QEMU Emulation
# Register QEMU binaries (for cross-platform builds)
docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
# Verify QEMU is available
docker run --rm --platform linux/arm64 alpine uname -m
# aarch64
# Build using emulation
docker buildx build --platform linux/arm64 -t myapp:arm64 .QEMU emulates different CPU architectures inside your current system. It is slower than native builds but allows building arm64 images on amd64 hosts. For faster builds, use native arm64 build runners.
Manifest Lists
# Inspect a manifest list
docker manifest inspect myregistry.com/myapp:1.0
# Example output:
# {
# "schemaVersion": 2,
# "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
# "manifests": [
# {
# "platform": { "architecture": "amd64", "os": "linux" },
# "digest": "sha256:abc123..."
# },
# {
# "platform": { "architecture": "arm64", "os": "linux" },
# "digest": "sha256:def456..."
# }
# ]
# }A manifest list is a pointer to platform-specific images. When you pull, Docker selects the matching platform automatically. The manifest list is stored as a single tag in the registry.
Testing Multi-Arch
# Test arm64 image on amd64 host using QEMU
docker run --rm --platform linux/arm64 myregistry.com/myapp:1.0
# Verify the architecture
docker run --rm --platform linux/arm64 alpine uname -m
# aarch64
# Use docker manifest to check what's available
docker manifest inspect myregistry.com/myapp:1.0 | jq '.manifests[].platform'
# Cross-platform build and test
docker buildx build --platform linux/amd64,linux/arm64 -t myapp:test .
docker run --rm --platform linux/arm64 myapp:testTest your multi-arch images by running them with --platform. Even on an amd64 host, QEMU can emulate arm64 to verify your image works correctly.
QEMU emulation is 5-10x slower than native builds. For CI/CD, use native arm64 runners (GitHub Actions supports them) instead of emulating on amd64. This reduces build time dramatically.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.