Cross-Architecture Builds: Producing amd64 and arm64 Images
Learn how to use docker buildx, QEMU emulation, and --platform linux/amd64,linux/arm64 to build and push multi-manifest container images.
Published on • November 17, 2026
AI Assistant

With developers running Apple Silicon Macs (arm64) and production environments running cloud servers (amd64 or AWS Graviton arm64), shipping single-architecture container images is no longer sufficient.
Docker Buildx—powered by Moby BuildKit—allows you to build multi-architecture container images simultaneously from a single workstation or CI/CD runner using QEMU emulation or remote builder nodes.
What is a Multi-Manifest Image?
A multi-architecture (multi-arch) image is not a giant image containing files for every platform. Instead, it is an OCI Image Index (or manifest list) stored in a container registry under a single tag (e.g., myregistry/app:v1.0.0).
When a client runs docker pull myregistry/app:v1.0.0:
- The Docker daemon queries the registry manifest list.
- The registry responds with the architecture options.
- The daemon automatically downloads only the layer set matching its host architecture (
linux/amd64orlinux/arm64).
+---------------------------+
| OCI Manifest List |
| myorg/app:latest |
+-------------+-------------+
|
+------------------------+------------------------+
| |
v v
+-------------------------+ +-------------------------+
| Manifest: linux/amd64 | | Manifest: linux/arm64 |
| Digest: sha256:1111... | | Digest: sha256:2222... |
+-------------------------+ +-------------------------+
Setting Up Docker Buildx and QEMU Emulation
Docker Buildx comes bundled with modern Docker Desktop and Docker Engine installations.
1. Enabling QEMU Emulation Handlers (Linux Only)
If you are running on a Linux host (e.g., Ubuntu GitHub Actions runner), register QEMU user-space emulators so BuildKit can execute non-native binaries during image builds:
docker run --privileged --rm tonistiigi/binfmt --install all
Verify supported platforms:
docker buildx ls
2. Creating a Custom Buildx Builder Instance
The default docker driver builder cannot store multi-architecture images directly in the local image store. You must create and switch to a docker-container driver builder:
# Create a new builder named 'multiarch-builder'
docker buildx create --name multiarch-builder --driver docker-container --use
# Boot and inspect the builder instance
docker buildx inspect --bootstrap
Output:
Name: multiarch-builder
Driver: docker-container
Nodes:
Name: multiarch-builder0
Endpoint: unix:///var/run/docker.sock
Status: running
Platforms: linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6
Building and Pushing Multi-Arch Images
To build for both linux/amd64 and linux/arm64 in a single invocation, use docker buildx build with the --platform flag and the --push action:
docker buildx build \
--platform linux/amd64,linux/arm64 \
-t myregistry.com/myuser/myapp:v1.0.0 \
-t myregistry.com/myuser/myapp:latest \
--push .
Important: Why
--push? Because a multi-arch manifest list cannot exist in the standard single-arch local Docker daemon image cache (docker images). Buildx pushes the manifest index and platform layers directly to the target registry.
Testing Multi-Arch Images Locally (--load)
If you want to test a build locally without pushing to a remote registry, build one platform at a time using --load to export the binary layer into your local daemon:
# Load amd64 image into local Docker daemon
docker buildx build --platform linux/amd64 -t myapp:local-amd64 --load .
# Load arm64 image into local Docker daemon
docker buildx build --platform linux/arm64 -t myapp:local-arm64 --load .
Inspecting the Remote Manifest List
After pushing your multi-arch image to Docker Hub or an OCI registry, verify the manifest index using docker buildx imagetools:
docker buildx imagetools inspect myregistry.com/myuser/myapp:v1.0.0
Sample verification output:
Name: myregistry.com/myuser/myapp:v1.0.0
MediaType: application/vnd.oci.image.index.v1+json
Digest: sha256:8f9e0d1c2b3a4f5e6d7c8b9a0f1e2d3c4b5a6f7e8d9c0b1a2f3e4d5c6b7a8f9e
Manifests:
Digest: sha256:a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890
MediaType: application/vnd.oci.image.manifest.v1+json
Platform: linux/amd64
Digest: sha256:f6e5d4c3b2a10987f6e5d4c3b2a10987f6e5d4c3b2a10987f6e5d4c3b2a10987
MediaType: application/vnd.oci.image.manifest.v1+json
Platform: linux/arm64
GitHub Actions Multi-Arch CI Workflow
Here is a GitHub Actions workflow snippet automating multi-arch builds on every release tag:
name: Build Multi-Arch Container Image
on:
push:
tags:
- 'v*'
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout Code
uses: actions/checkout@v4
- name: Set up QEMU
uses: docker/setup-qemu-action@v3
- name: Set up Docker Buildx
uses: docker/setup-buildx-action@v3
- name: Log in to Docker Hub
uses: docker/login-action@v3
with:
username: ${{ secrets.DOCKERHUB_USERNAME }}
password: ${{ secrets.DOCKERHUB_TOKEN }}
- name: Build and Push Multi-Arch Image
uses: docker/build-push-action@v6
with:
context: .
platforms: linux/amd64,linux/arm64
push: true
tags: |
${{ secrets.DOCKERHUB_USERNAME }}/myapp:${{ github.ref_name }}
${{ secrets.DOCKERHUB_USERNAME }}/myapp:latest
Takeaway: docker buildx build --platform linux/amd64,linux/arm64 --push allows you to target multiple CPU architectures in a single workflow. Combine BuildKit container drivers, QEMU emulation, and OCI manifest lists to deliver seamless cross-architecture container images.