buildkit/docs/multi-platform.md

Building multi-platform images

⚡ For building multi-platform images with docker buildx, see the docker buildx documentation.

BuildKit provides built-in support for building multi-platform by setting a comma-separated list of platform specifiers as platform option.

buildctl build \
  --frontend dockerfile.v0 \
  --opt platform=linux/amd64,linux/arm64 \
  --output type=image,name=docker.io/username/image,push=true \
  ...

When your build needs to run a binary for architecture that is not supported natively by your host, it gets executed using a QEMU user-mode emulator. You do not need to set up QEMU manually in most cases.

Troubleshooting

Error exec user process caused: exec format error

You may face an error like exec user process caused: exec format error, mostly when you are using a third-party package of BuildKit that lacks buildkit-qemu-* binaries.

In such a case, you have to download the official binary release of BuildKit from https://github.com/moby/buildkit/releases , and install the buildkit-qemu-* binaries in the release archive into the $PATH of the host.

You may also face exec format error when the container contains mix of binaries for multiple architectures.

In such a case, you have to register QEMU into /proc/sys/fs/binfmt_misc so that the kernel can execute foreign binaries using QEMU.

QEMU is registered into /proc/sys/fs/binfmt_misc by default on Docker Desktop. On other environments, the common way to register QEMU is to use tonistiigi/binfmt Docker image.

docker run --privileged --rm tonistiigi/binfmt --install all

See also tonistiigi/binfmt documentation.