README.md

May 27, 2026 · View on GitHub

About

GitHub Action to install QEMU static binaries.

Screenshot

Usage
Customizing
- inputs
- outputs
Contributing

Usage

name: ci

on:
  push:

jobs:
  qemu:
    runs-on: ubuntu-latest
    steps:
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v4

This action registers QEMU emulators with binfmt_misc, so later steps can run containers built for another architecture on the GitHub-hosted runner.

name: run-cross-platform-container

on:
  workflow_dispatch:

jobs:
  qemu-example:
    runs-on: ubuntu-latest
    steps:
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v4
      -
        name: Run an arm64 container
        run: docker run --rm --platform linux/arm64 alpine uname -m

The command above prints aarch64 even though the job itself is running on ubuntu-latest.

Tip

setup-qemu-action enables user-mode emulation for registered platforms. It does not install qemu-system-* tools or add qemu-* binaries to your PATH.

Note

If you are using docker/setup-buildx-action, this action should come before it:

    -
      name: Set up QEMU
      uses: docker/setup-qemu-action@v4
    -
      name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v4

Customizing

inputs

The following inputs can be used as step.with keys:

Name	Type	Default	Description
`image`	String	`tonistiigi/binfmt:latest`	QEMU static binaries Docker image
`platforms`	String	`all`	Platforms to install (e.g., `arm64,riscv64,arm`)
`reset`	Bool	`false`	Uninstall current emulators before installation
`cache-image`	Bool	`true`	Cache binfmt image to GitHub Actions cache backend

outputs

The following outputs are available:

Name	Type	Description
`platforms`	String	Available platforms (comma separated)

Contributing

Want to contribute? Awesome! You can find information about contributing to this project in the CONTRIBUTING.md