docker/setup-buildx-action

Set up Docker Buildx so a workflow can do multi-platform builds and layer caching.

Official actionCategory: Docker & ContainersLatest v3View on GitHub

What it does

docker/setup-buildx-action installs and starts a Buildx builder using the docker-container driver, which is what enables multi-platform builds and the type=gha cache backend.

It is the step you add right before docker/build-push-action.

Usage

workflow (.yml)

steps:
  - uses: docker/setup-buildx-action@v3
  - uses: docker/build-push-action@v6
    with:
      tags: myorg/app:ci

Inputs

Input	Description	Default	Required
`driver`	Buildx driver to use.	`docker-container`	No
`driver-opts`	Options passed to the driver.	-	No
`platforms`	Fixed platforms for the builder.	-	No
`install`	Set Buildx as the default docker builder.	`false`	No

Outputs

Output	Description
`name`	Name of the builder instance.
`platforms`	Platforms the builder supports.

Notes

The default docker-container driver is what makes cache-to: type=gha work; the default docker driver does not support it.

Common errors

Cache export is not supported for the docker driver means Buildx is using the plain docker driver. setup-buildx-action selects docker-container, which supports it.

Security and pinning

Pin to a commit SHA.

Alternatives and related

docker/build-push-actionBuild and push a Docker image using Buildx, with cache and multi-platform support. docker/setup-qemu-actionInstall QEMU emulators so a workflow can build container images for other CPU architectures.

Frequently asked questions

Do I always need setup-buildx-action?

For layer caching with type=gha or multi-platform builds, yes. For a simple single-arch build without caching you can skip it.