BuildKit — the modern builder · Docker & Containers

BuildKit is the modern builder for Docker images. It is the default builder for Docker Engine and Docker Desktop users. It produces better images faster than the legacy builder and unlocks features the legacy builder cannot support.

It is also a genuinely separate piece of software from dockerd, with its own graph model, its own cache store and — depending on how you invoke it — its own process or even its own host. Nearly every “BuildKit is behaving strangely” ticket is really a question about which BuildKit you were talking to.

Enabling BuildKit

For Docker 23+, BuildKit is the default. To verify:

docker buildx version
docker info | grep -i buildkit

To force BuildKit on older Docker:

DOCKER_BUILDKIT=1 docker build .

Or via daemon config:

{
  "features": {
    "buildkit": true
  }
}

The classic builder still exists on Engine 28.x and can be selected with DOCKER_BUILDKIT=0, but Docker’s deprecation page is unambiguous: v23.0 “marks the beginning of the deprecation cycle of the classic (‘legacy’) builder for Linux images.” No removal date is published, which makes it exactly the kind of dependency that is fine until the release where it is not. If a build in your estate still needs DOCKER_BUILDKIT=0, that is a migration ticket, not a setting.

What BuildKit actually is

Frontend, LLB, and the solver

BuildKit does not interpret your Dockerfile line by line. It runs a three-stage pipeline:

A frontend converts a human-readable build format into LLB. Docker’s own description: “A frontend is a component that takes a human-readable build format and converts it to LLB so BuildKit can execute it.” The Dockerfile frontend is dockerfile.v0.
LLB — the Low-Level Build definition — is “an intermediate binary format that allows developers to extend BuildKit.” It is a directed acyclic graph of content-addressed operations: “run this command over that filesystem state”, “fetch this image”, “copy these paths from that vertex”.
The solver walks the graph, deduplicates identical vertices, checks each one against the cache, and executes whatever is left.

Three behaviours fall directly out of the graph model, and none of them are possible in a line-by-line builder:

Independent stages run in parallel. Two FROM stages that do not reference each other are separate branches of the DAG, so BuildKit schedules both at once. A four-stage Dockerfile can finish in the time of its longest branch rather than the sum.
Unreferenced stages are never built. If nothing in the final stage’s ancestry reaches a stage, that stage is not in the graph the solver is asked to resolve. The legacy builder executed every stage top to bottom whether or not the result was used.
Identical work is done once. Two stages that begin with the same FROM and the same RUN share one vertex, so the command runs once and both stages consume the result.

This is also why the build output numbers steps as #7 [3/5] rather than by Dockerfile line number: the number is a vertex in the graph, and the graph is not the file.

Where BuildKit runs: the driver decides

docker buildx can drive four different builders, and the choice changes where the engine lives, where the cache lives, and where a finished image lands.

Driver	Where the engine runs	Multi-platform	Cache export	Image lands where
`docker` (default)	Inside `dockerd`	No	Limited	Local image store, automatically
`docker-container`	A `moby/buildkit` container on the host	Yes	Full	Nowhere, until `--load` or `--push`
`kubernetes`	Pods in a cluster	Yes	Full	Nowhere, until `--load` or `--push`
`remote`	An already-running buildkitd you point at	Yes	Full	Nowhere, until `--load` or `--push`

The default docker driver, in Docker’s words, “prioritizes simplicity and ease of use” — and it buys that simplicity by embedding BuildKit in the daemon, which is why it cannot build multi-platform images and why its cache export options are restricted.

Read-only / Safewhich builder— List builders and inspect the active one. --bootstrap starts a container driver if it is not already up.

docker buildx ls
docker buildx inspect --bootstrap

Read-only / Safebuildx ls— Two builders on one host: the embedded default, and a container driver created for multi-platform work.

$ docker buildx ls

NAME/NODE         DRIVER/ENDPOINT     STATUS    BUILDKIT   PLATFORMS
multiarch*        docker-container
\_ multiarch0     \_ unix:///var/run/docker.sock  running  v0.20.2   linux/amd64, linux/arm64, linux/arm/v7
default           docker
\_ default        \_ default                      running  v0.20.2   linux/amd64

Illustrative output

The asterisk marks the selected builder. That one character is the answer to a surprising share of build mysteries.

The build succeeded and the image does not exist

$ docker buildx build -t myorg/myapp:dev .
...
 => exporting to image                                          0.4s
 => => exporting layers                                         0.3s
$ docker run --rm myorg/myapp:dev
Unable to find image 'myorg/myapp:dev' locally
docker: Error response from daemon: pull access denied for myorg/myapp

Nothing is broken. Somebody ran docker buildx create --use on this host — perhaps months ago, to do one multi-platform build — and the selected builder is still the docker-container driver. That driver’s BuildKit has its own content store inside its own container. The build genuinely succeeded; the result is sitting in a store dockerd cannot see, so docker images does not list it and docker run tries to pull it from Docker Hub.

The first diagnosis is almost always wrong, because the error text says “pull access denied” and sends people to check registry credentials.

Check the builder before you check anything else:

docker buildx ls

Then either export the result into the local image store with --load, or push it:

docker buildx build --load -t myorg/myapp:dev .
docker buildx build --push -t registry.example.com/myorg/myapp:dev .

--load is only needed for the non-docker drivers; the default driver loads automatically. And --load cannot take a multi-platform build unless the daemon is using the containerd image store, because the legacy image store has nowhere to put a multi-platform index.

The `# syntax=` directive

This is the most operationally useful BuildKit feature that most people never turn on.

# syntax=docker/dockerfile:1
FROM alpine:3.21
RUN --mount=type=cache,target=/var/cache/apk apk add curl

The directive names a frontend image. BuildKit pulls it and uses it to parse the Dockerfile, instead of using whatever frontend is compiled into the daemon. The consequence, in Docker’s words, is that you “use the latest features without updating the Docker daemon” and “automatically get bug fixes without updating the Docker daemon.”

For a fleet, that inverts a painful dependency. Dockerfile features — --mount=type=secret, COPY --link, COPY --parents, heredocs — normally arrive with an Engine upgrade, which is a change-controlled, container-restarting event. With the syntax directive they arrive with a pull of a small frontend image, which disturbs nothing that is running.

Two channels are published:

docker/dockerfile:1 — stable, tracks the latest 1.x.x.
docker/dockerfile:1-labs — the same plus experimental features.

The BuildKit cache model

BuildKit’s cache is content-addressable. Each build step has an identifier derived from:

The instruction’s text.
The contents of files referenced by the instruction.
The cache key passed to the step.
The build arguments.

If two builds have identical inputs, they share cached output. This is true across machines: a CI runner’s cache can be pushed to a registry and pulled by a developer’s machine.

# Push the cache to a registry after a build
docker buildx build --push --cache-to=type=registry,ref=myorg/myapp:cache,mode=max .

# Pull the cache for a new build
docker buildx build --cache-from=type=registry,ref=myorg/myapp:cache .

The mode=max cache stores every layer, not just the final one. This makes CI caches reusable for arbitrary branches.

The next lesson takes the key rules apart instruction by instruction; what matters here is that this cache belongs to the builder, not to the daemon and not to the image store. docker buildx rm deletes it. docker system prune does not reach into a docker-container builder to clear it.

buildx — the modern CLI

docker buildx is the CLI for BuildKit. It supports:

Multi-platform builds (--platform linux/amd64,linux/arm64).
Multiple builders (docker buildx create --name ci).
Inline cache output (--cache-to=type=inline).
Secrets (--secret id=key,src=./key.pem).
SSH forwarding (--ssh default).

# Create a builder that supports multi-platform
docker buildx create --use --name multiarch

# Multi-platform build
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag myorg/myapp:1.0.0 \
  --push \
  .

Inspect the active builder:

docker buildx inspect --bootstrap

docker buildx create defaults to the docker-container driver, which is why the command above both enables multi-platform builds and silently changes where your images land. Read the previous callout again before running it on a shared build host.

Build secrets

BuildKit can pass secrets to RUN steps without baking them into layers:

RUN --mount=type=secret,id=github_token \
  curl -H "Authorization: Bearer $(cat /run/secrets/github_token)" \
    https://api.example.com/v1/artifacts

docker buildx build --secret id=github_token,src=./token .

The secret is mounted at /run/secrets/<id> during the build step. It is not present in any layer. After the step, the secret is gone.

Why the secret cannot leak into a layer

The secret is mounted by the build runner into the build container for the duration of one RUN step. It is a tmpfs mount that exists in the mount namespace of that step alone. When the step finishes, BuildKit snapshots the filesystem changes the command made — and the mount point is not one of them, because a mount is not a filesystem change to the layer underneath it.

Docker’s cache-invalidation reference makes the second half of the guarantee explicit: “The contents of build secrets are not part of the build cache.” So the value is absent from the exported cache as well as from the image. What does participate is the shape: “Properties of secrets such as IDs and mount paths do participate in the cache checksum.”

If the secret’s contents leak into the layer through some other mechanism — an echo of the secret into a file, a build log that prints it, a config file the command writes with the token substituted in — that file is in the layer and the secret is exposed. The protection is “the secret file itself is not in any layer”, not “the secret cannot appear in a layer”.

SSH mount

For builds that need SSH access (e.g. pulling private Go modules):

RUN --mount=type=ssh \
  go mod download

docker buildx build --ssh default .

The host’s SSH agent is forwarded to the build container for the duration of the step.

Inline cache output

For builds whose cache should travel with the image:

docker buildx build --cache-to=type=inline .

The cache metadata is embedded in the image manifest. When a CI runner pulls the image, it can use the cache for the next build without a separate cache store.

Verifying the build engine you are using

Three checks that can each fail, in the order worth running them:

Read-only / Safeverify— Which builder is selected, which BuildKit version it runs, and whether the daemon has an embedded one.

docker buildx ls
docker buildx inspect --bootstrap | grep -E 'Name|Driver|Buildkit|Platforms'
docker info --format '{{.DriverStatus}}'

Read-only / Safeinspect— The active builder's driver and BuildKit version. The Driver line is the one that determines where images land.

$ docker buildx inspect --bootstrap

Name:          default
Driver:        docker
Last Activity: 2026-08-12 09:14:03 +0000 UTC

Nodes:
Name:             default
Endpoint:         default
Status:           running
BuildKit version: v0.20.2
Platforms:        linux/amd64, linux/386

Illustrative output

If Driver says docker, images go straight into the local image store. If it says anything else, they do not unless you ask.

What if the build host's cache directory fills?

For the default docker driver, BuildKit’s cache lives under /var/lib/docker/buildkit. For a docker-container builder it lives in that builder’s own volume. Either way it grows without an explicit bound.

When the filesystem holding /var/lib/docker fills, the damage is not confined to builds. dockerd can no longer write layers, so image pulls fail; it can no longer write container logs, so json-file logging errors; and a container that stops cannot be restarted because its writable layer cannot be created. A build problem becomes a production outage.

Bound it deliberately. BuildKit garbage collection is configured per builder — in the daemon’s builder configuration for the default driver, in buildkitd.toml for a container driver — and a scheduled prune is the blunt fallback.

Destructiveprune— Reports cache usage, then deletes cache records older than 7 days. No image, container or volume is affected; subsequent builds are slower until the cache refills.

docker buildx du
docker buildx prune --filter until=168h

Verify it worked with the number, not the feeling: docker buildx du before and after, and df -h /var/lib/docker.