docker buildx build Command Reference

Build images with the full BuildKit feature set, including remote cache and multi-arch.

docker buildx build is the BuildKit-backed build command. It adds capabilities the classic builder lacks: pushing directly from the build, importing and exporting layer cache from external backends, and building for multiple platforms in one invocation.

Common flags

--push - build and push to the registry in one step (implies --output type=registry)
--load - load the result into the local image store (single platform only)
--platform - comma-separated target platforms, e.g. linux/amd64,linux/arm64
--cache-from - import cache, e.g. type=gha or type=registry,ref=...
--cache-to - export cache, e.g. type=gha,mode=max
--tag, --build-arg, --target, --file - same meaning as docker build
--provenance - attach (or disable with =false) SLSA provenance attestations

Example

shell

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --cache-from type=gha \
  --cache-to type=gha,mode=max \
  -t myorg/app:${{ github.sha }} \
  --push \
  .

In CI

Use --cache-to type=gha,mode=max with --cache-from type=gha to persist BuildKit layer cache in the GitHub Actions cache across runs; mode=max caches intermediate stages too. For multi-arch images you must --push (you cannot --load more than one platform). On Latchkey managed runners the GitHub Actions cache backend works the same as on hosted runners.

Key takeaways

type=gha cache import/export reuses BuildKit layers across CI runs for faster builds.
Multi-platform builds require --push; --load only works for a single architecture.
mode=max caches intermediate build stages, not just the final image layers.