Collabnix / Cheatsheets
All cheatsheets
BuildIntermediate

Docker Buildx Cheatsheet

Next-gen image builder powered by BuildKit, with multi-platform, bake, and history.

What it is

Use Buildx for fast, cached, multi-platform image builds, parallel builds via bake, and to inspect build history and cache usage.

Installation

Bundled with Docker Desktop and modern Docker Engine. `docker build` is an alias for `docker buildx build`. Confirm with `docker buildx version`.

Quick start

docker buildx create --use --name multi

Create and select a builder.

docker buildx build -t app:dev --load .

Build and load into local image store.

docker buildx build --platform linux/amd64,linux/arm64 -t me/app:1.0 --push .

Multi-arch build pushed to a registry.

docker buildx bake

Run targets defined in docker-bake.hcl / .json / compose.

Common commands

TaskCommandDescription
Create builder
docker buildx create --name multi --use
Creates a BuildKit builder and switches to it.
Select builder
docker buildx use multi
Switch the active builder.
Inspect builder
docker buildx inspect --bootstrap
Show driver, platforms, status.
Build image
docker buildx build -t app:dev .
Default builder, current context.
Bake targets
docker buildx bake
Build one or more targets from HCL/JSON/compose.
Cache usage
docker buildx du
Show BuildKit cache disk usage.
Build history
docker buildx history
List recent builds with this builder.
Open build in UI
docker buildx history open <ref>
Open a build record in Docker Desktop / Build Cloud UI.
Export build record
docker buildx history export <ref> -o build.dockerbuild
Save a portable build record.

Useful flags

FlagExampleMeaning
--platform
--platform linux/amd64,linux/arm64
Comma-separated target platforms.
--push
--push
Push the result to the registry (required for multi-arch).
--load
--load
Load the result into the local image store (single platform only).
--cache-from
--cache-from type=registry,ref=me/app:cache
Import build cache from a source.
--cache-to
--cache-to type=registry,ref=me/app:cache,mode=max
Export build cache to a destination.
--build-arg
--build-arg NODE_VERSION=20
Pass a build-time variable.
--secret
--secret id=npmrc,src=$HOME/.npmrc
Mount a secret into the build (BuildKit).

Real-world examples

Multi-arch build, push, with registry cache

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --cache-from type=registry,ref=me/app:cache \
  --cache-to   type=registry,ref=me/app:cache,mode=max \
  -t me/app:1.0 --push .

Minimal docker-bake.hcl

group "default" { targets = ["api", "web"] }
target "api" { context = "./api" tags = ["me/api:dev"] }
target "web" { context = "./web" tags = ["me/web:dev"] }

Pass a secret without baking it into a layer

docker buildx build --secret id=token,env=GITHUB_TOKEN -t app .

Best practices

  • Create a dedicated builder per project so caches don't compete.
  • Use --cache-to/--cache-from with mode=max for shared CI cache.
  • Prefer --secret over --build-arg for tokens; --build-arg leaks into image history.
  • Use bake to parallelize related builds and keep CI configs in version control.
  • For multi-arch images always --push; --load only supports a single platform.

Troubleshooting

ERROR: multiple platforms feature is currently not supported for docker driver

Create a docker-container or cloud builder.

docker buildx create --use --name multi

Build is slow on every run

Wire up a remote cache.

docker buildx build --cache-from type=registry,ref=me/app:cache --cache-to type=registry,ref=me/app:cache,mode=max .

Disk full from BuildKit cache

Inspect and prune cache.

docker buildx du && docker buildx prune -af

Official Docker Docs references

Last reviewed: