docker/setup-qemu-action

Install QEMU emulators so a workflow can build container images for other CPU architectures.

Official actionCategory: Docker & ContainersLatest v3View on GitHub

What it does

docker/setup-qemu-action installs QEMU so the runner can emulate non-native architectures during a Buildx build, which is how you produce arm64 images on an amd64 runner.

Add it before docker/setup-buildx-action when building multiple platforms.

Usage

workflow (.yml)

steps:
  - uses: docker/setup-qemu-action@v3
  - uses: docker/setup-buildx-action@v3
  - uses: docker/build-push-action@v6
    with:
      platforms: linux/amd64,linux/arm64
      tags: myorg/app:multi

Inputs

Input	Description	Default	Required
`platforms`	Platforms to install emulators for.	`all`	No
`image`	QEMU static binaries image to use.	`tonistiigi/binfmt`	No

Outputs

Output	Description
`platforms`	Platforms now available for emulation.

Notes

Emulated builds are much slower than native. For heavy arm64 builds, consider native arm runners instead of QEMU.

Common errors

exec format error during a multi-arch build means QEMU is not set up. Add setup-qemu-action before the build.

Security and pinning

Pin both this action and the image to fixed versions/SHAs.

Alternatives and related

docker/setup-buildx-actionSet up Docker Buildx so a workflow can do multi-platform builds and layer caching. docker/build-push-actionBuild and push a Docker image using Buildx, with cache and multi-platform support.

Frequently asked questions

Why is my arm64 build so slow?

QEMU emulates the target CPU, which is slow. Native arm64 runners build far faster than emulation for large images.