How to Build Multi-Arch Docker Images With Buildx

docker/build-push-action with a platforms list builds every architecture in one pass and pushes a single manifest that clients resolve to their arch.

Set up Buildx, then pass platforms: linux/amd64,linux/arm64 to docker/build-push-action. The action builds each architecture and publishes a manifest list under one tag.

Steps

• Add docker/setup-buildx-action to create a Buildx builder.
• Log in to the registry with docker/login-action.
• Pass platforms: linux/amd64,linux/arm64 to docker/build-push-action with push: true.

Workflow

jobs:
  image:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ghcr.io/${{ github.repository }}:latest

Gotchas

• On an amd64 runner the arm64 layer builds under emulation and is slower; add QEMU or use a native arm64 runner.
• The registry stores one manifest list; docker pull on each host selects the matching architecture automatically.

Related guides