Skip to content

[docs-scanner] Contradictory QEMU requirements for multi-platform builds #25292

@github-actions

Description

@github-actions

File: content/manuals/build/building/multi-platform.md

Issue

The document contains contradictory information about QEMU requirements for multi-platform builds. In the "Prerequisites" section:

If you're using Docker Engine standalone and you need to build multi-platform
images using emulation, official BuildKit releases bundle QEMU user-mode
emulators, so in most cases you don't need to install QEMU manually.

But then in the "QEMU" strategy section under "Install QEMU manually":

The prerequisites for installing QEMU are:

  • Linux kernel version 4.8 or later
  • binfmt-support version 2.1.7 or later
  • The QEMU binaries must be statically compiled and registered with the
    fix_binary flag

And then:

Use the tonistiigi/binfmt image to
install QEMU and register the executable types on the host with a single
command:

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

Why this matters

A reader trying to set up multi-platform builds would be confused about whether they need to manually install QEMU or not. The document first says "you don't need to install QEMU manually" because BuildKit bundles it, but then provides detailed instructions for manual installation without clearly explaining when the bundled version is insufficient. The relationship between the bundled QEMU and the manual installation process is unclear.

Suggested fix

Clarify the conditions under which manual QEMU installation is necessary:

  1. State clearly that Docker Desktop and recent Docker Engine versions with bundled BuildKit don't need manual QEMU setup
  2. Explain that manual installation is only needed for:
    • Third-party BuildKit packages that don't ship bundled emulators
    • Older Docker Engine versions
    • Custom BuildKit installations
  3. Move the manual installation section under a clear heading like "When manual QEMU installation is required" or "Troubleshooting QEMU emulation"

Found by nightly documentation quality scanner

Metadata

Metadata

Assignees

No one assigned

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions