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:

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

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:

<code>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
</code>

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