From b5690ded0635ef302cd171762080f5bfa8ac4d8a Mon Sep 17 00:00:00 2001 From: Louis-Arnaud Catoire Date: Thu, 16 Apr 2026 18:28:25 +0200 Subject: [PATCH] docs: note that BuildKit bundles QEMU emulators for multi-platform builds BuildKit ships QEMU user-mode emulators in official releases, so a manual QEMU install is a fallback rather than a default prerequisite for Docker Engine standalone. Reword the Prerequisites pointer and the Install QEMU manually intro accordingly. Closes #22899 --- content/manuals/build/building/multi-platform.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/content/manuals/build/building/multi-platform.md b/content/manuals/build/building/multi-platform.md index 9f35400e5bb1..8ffae449a5db 100644 --- a/content/manuals/build/building/multi-platform.md +++ b/content/manuals/build/building/multi-platform.md @@ -89,8 +89,11 @@ $ docker buildx create \ > drivers](/manuals/build/builders/drivers/_index.md). If you're using Docker Engine standalone and you need to build multi-platform -images using emulation, you also need to install QEMU, see [Install QEMU -manually](#install-qemu-manually). +images using emulation, official BuildKit releases bundle QEMU user-mode +emulators, so in most cases you don't need to install QEMU manually. See +[Install QEMU manually](#install-qemu-manually) if emulation fails, for +example with a third-party BuildKit package that doesn't ship the bundled +emulators. ## Build multi-platform images @@ -131,10 +134,10 @@ QEMU that's bundled within the Docker Desktop VM. #### Install QEMU manually -If you're using a builder outside of Docker Desktop, such as if you're using -Docker Engine on Linux, or a custom remote builder, you need to install QEMU -and register the executable types on the host OS. The prerequisites for -installing QEMU are: +If the QEMU emulators bundled with BuildKit don't work for your build, for +example with a third-party BuildKit package that doesn't ship them, you can +install QEMU and register the executable types on the host OS. The +prerequisites for installing QEMU are: - Linux kernel version 4.8 or later - `binfmt-support` version 2.1.7 or later