Binfmt

Cross-platform emulator collection distributed with Docker images.

Build local binaries

docker buildx bake

This builds the qemu-user emulator binaries for your local plaform to the bin directory.

Build test image

REPO=myuser/binfmt docker buildx bake --load mainline
docker run --privileged --rm myuser/binfmt

Prints similar to:

{
  "supported": [
    "linux/amd64",
    "linux/arm64",
    "linux/riscv64",
    "linux/ppc64le",
    "linux/s390x",
    "linux/386",
    "linux/arm/v7",
    "linux/arm/v6"
  ],
  "emulators": [
    "qemu-aarch64",
    "qemu-arm",
    "qemu-i386",
    "qemu-ppc64le",
    "qemu-riscv64",
    "qemu-s390x"
  ]
}

Installing emulators

docker run --privileged --rm tonistiigi/binfmt --install all
docker run --privileged --rm tonistiigi/binfmt --install arm64,riscv64,arm

Installing emulators from Docker-Compose

version: "3"
services:
  emulator:
    image: tonistiigi/binfmt
    container_name: emulator
    privileged: true
    command: --install all
    network_mode: bridge
    restart: "no"

Only use container restart-policy as no, otherwise docker will keep restarting the container.

Uninstalling emulators

docker run --privileged --rm tonistiigi/binfmt --uninstall qemu-aarch64

Emulator names can be found from the status output.

You can also uninstall all archs for a specific emulator:

docker run --privileged --rm tonistiigi/binfmt --uninstall qemu-*

Display version

docker run --privileged --rm tonistiigi/binfmt --version

binfmt/9a44d27 qemu/v6.0.0 go/1.15.11

Development commands

# validate linter
./hack/lint

# validate vendored files
./hack/validate-vendor

# update vendored files
./hack/update-vendor

# test, only run on nodes where you allow emulators to be installed in kernel
./hack/install-and-test

Test current emulation support

docker run --rm --platform linux/arm64 alpine uname -a
docker run --rm --platform linux/arm/v7 alpine uname -a
docker run --rm --platform linux/ppc64le alpine uname -a
docker run --rm --platform linux/s390x alpine uname -a
docker run --rm --platform linux/riscv64 alpine uname -a

buildkit target

This repository also provides helper for BuildKit's automatic emulation support https://github.com/moby/buildkit/pull/1528. These binaries are BuildKit specific and should not be installed in kernel with binfmt_misc.

Licenses

MIT. See LICENSE for more details. For QEMU see https://wiki.qemu.org/License