Multi Platform Builds Docker

April 9, 2025 · 2 min read · Page View:

If you have any questions, feel free to comment below.

This is a viable build record. The multi platform builds are supported by docker buildx¹, which is related to binfmt_misc and QEMU.

binfmt_misc #

The binfmt_misc²(Miscellaneous Binary Format) is a linux kernel feature that allows arbitrary executable file formats to be recognized and passed to certain user space applications, such as emulators and virtual machines.

QEMU #

The Quick Emulator (QEMU)³ is a free and open-source emulator that uses dynamic binary translation to emulate a computer’s processor. In short, QEMU can be used with a Kernel-based Virtual Machine (KVM) to emulate hardware at near-native speeds. Due to the ability of QEMU, so even you are running a arm64 container on a amd64 machine, sometimes it still works.

The docker builds on multi platforms, like linux/amd64, linux/arm64, linux/arm/v7, etc. It needs to install QEMU, enabling QEMU to execute non-native file formats for emulation.

The mode of QEMU emulation is as follows:

QEMU will register a binary conversion handler through binfmt_misc in the Linux kernel.
When the program runs, QEMU dynamically translates the binary file according to the needs, converting the system calls from the target CPU architecture to the current system’s CPU architecture.

So the final effect looks like running the binary file of the target CPU architecture locally.

Prerequisites #

Linux kernel version 4.8 or later
binfmt-support version 2.1.7 or later. Check the version apt-cache policy binfmt-support
The QEMU binaries must be statically compiled and registered with the fix_binary flag. Check the version apt-cache policy qemu-user-static

If not, install apt-get install -y qemu-user-static binfmt-support.

Install QEMU #

docker run --privileged --rm tonistiigi/binfmt --install all
# check QEMU
ls /proc/sys/fs/binfmt_misc/qemu-*
# check interpreter
cat /proc/sys/fs/binfmt_misc/qemu-aarch64

Buildx #

Buildx is a plugin for docker build, it can build multi-platform images. docker buildx -h to get more information.

docker buildx create \
  --name multi-builder \
  --driver docker-container \
  --bootstrap --use

Then use the multi-builder to build multi-platform images.

# Load the image to the local registry
docker buildx build -t username/repository:tag --platform=linux/amd64 --load .
# ATTENTION: The multi-platform builds cannot load to the local registry.
docker buildx build -t username/repository:tag --platform=linux/arm64,linux/amd64 . --push
# inspect image
docker buildx imagetools inspect username/repository:tag

Other method: manifest #

Also, you can build the images on their own platforms and tags example:1.0.0-arm64, example:1.0.0-amd64, and then push them to the registry. Then you can use the docker manifest to manage the multi-platform images.

# create manifest
docker manifest create username/repository:tag \
  --amend username/repository:tag-amd64 \
  --amend username/repository:tag-arm64
# push manifest
docker manifest push username/repository:tag
# inspect manifest
docker manifest inspect username/repository:tag