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

Task	Command	Description
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.

Useful flags

Flag	Example	Meaning
`--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.
`--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.

Real-world examples

Multi-arch build 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

Multiple platforms 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 .

Disk full from BuildKit cache

Inspect and prune cache.

docker buildx du && docker buildx prune -af

Related cheatsheets

Last reviewed: 2026-06-15