How to Build Multi‑Architecture Docker Images with Buildx and BuildKit

Tool Overview

Docker Buildx is a CLI plugin that extends Docker commands with BuildKit features, providing the same user experience as docker build while adding new capabilities such as multi‑architecture builds. It requires Docker 19.03+ and a Linux kernel ≥ 4.8 for fix_binary support.

How Buildx Works

Buildx calls the BuildKit API; the ability to build for multiple platforms depends on the BuildKit environment. By specifying the --platform flag (e.g., linux/amd64, linux/arm64), you tell BuildKit which target platforms to produce.

When the builder runs in a Docker‑container or Kubernetes driver, Buildx can generate a manifest list containing images for all requested architectures, and Docker will select the appropriate image at runtime.

Three strategies are supported for multi‑platform images:

Use QEMU emulation in the kernel.

Build on multiple native nodes with the same builder instance.

Cross‑compile in a multi‑stage Dockerfile.

Enabling Buildx

Buildx is experimental in Docker 19.03, so you must enable it. You can permanently enable experimental features by adding {"experimental":"enabled"} to ~/.docker/config.json, or temporarily by setting the environment variable DOCKER_CLI_EXPERIMENTAL=enabled.

Create a Builder Instance

Use docker buildx create to create a new builder that supports the --platform flag. Example commands for domestic mirrors and Tencent Cloud are provided. After creation, select the builder with docker buildx use <name> and list builders with docker buildx ls.

Write a Multi‑Platform Dockerfile

A simple Dockerfile using the built‑in $TARGETPLATFORM variable might look like:

mkdir ~/demo
cd ~/demo
cat > Dockerfile <<EOF
FROM --platform=$TARGETPLATFORM alpine
RUN uname -a > /os.txt
CMD cat /os.txt
EOF

The Alpine base image supports seven architectures:

linux/amd64, linux/arm/v6, linux/arm/v7, linux/arm64/v8, linux/386, linux/ppc64le, linux/s390x

(also referenced as amd64, arm32v6, arm32v7, arm64v8, i386, ppc64le, s390x).

Build and Push the Image

Run the build with:

docker buildx build \
  --platform linux/amd64,linux/arm/v6,linux/arm/v7,linux/arm64/v8,linux/386,linux/ppc64le,linux/s390x \
  -t yourusername/hello . --push

After the push, you can inspect the manifest list with docker buildx imagetools inspect yourusername/hello to verify all platforms are present.

Final Tips

Building multi‑architecture images is CPU‑intensive; use a powerful multi‑core VPS or CI/CD pipeline for faster results. The article focuses on manual builds, but the same steps can be automated.

References

Docker image manifest guide

Docker Buildx installation page