Skip to content
Tutorials Center
My learning

Topics

Lesson 28 of 111 ยท Dockerfiles

BuildKit and buildx

Learn BuildKit and docker buildx: cache mounts, secret mounts, SSH mounts, heredocs, build checks, output types, bake files and builders, with real build output.

Every docker build you have run in this course was executed by BuildKit, Docker's modern build engine. It replaced the old "classic" builder years ago and is the default in Docker 29. BuildKit runs independent steps in parallel, skips stages nobody needs, caches precisely, and adds Dockerfile features the old builder never had: cache mounts that keep package downloads between builds, secret mounts that let a build use a password without storing it in the image, heredocs for readable multi-line scripts, and build checks that lint your Dockerfile.

The command you drive it with is buildx. docker build is in fact a shortcut for docker buildx build, so everything in this lesson works with either spelling. All output below comes from real builds on Docker Engine 29.8 with buildx 0.37.

BuildKit, buildx and builders

Three names, three roles:

  • BuildKit is the engine. It reads your Dockerfile, turns it into a graph of steps, and executes the graph.
  • buildx is the CLI plugin that talks to BuildKit. It adds output types, multi-platform builds, cache export and bake files.
  • A builder is a configured BuildKit instance. You can have several and pick one per build.

List yours:

CONSOLE
$ docker buildx ls
NAME/NODE           DRIVER/ENDPOINT     STATUS    BUILDKIT   PLATFORMS
default             docker                                   
 \_ default          \_ default         running   v0.33.0    linux/amd64 (+3), linux/arm64, linux/arm (+2), linux/ppc64le, (2 more)
desktop-linux*      docker                                   
 \_ desktop-linux    \_ desktop-linux   running   v0.33.0    linux/amd64 (+3), linux/arm64, linux/arm (+2), linux/ppc64le, (2 more)

The star marks the builder used by default. The docker driver means BuildKit runs inside the Docker daemon itself, which is the simplest setup and what you get out of the box. A second driver, docker-container, runs BuildKit in its own container; it is what you need for some advanced exports and cache backends (more on that near the end of this lesson).

Reading build output

By default BuildKit draws a compact, live progress display. When a build fails or you are pasting logs into a bug report, switch to the plain log:

CONSOLE
$ docker build --progress=plain -t tcd-demo .
#1 [internal] load build definition from Dockerfile
#2 [internal] load metadata for docker.io/library/alpine:3.22
#3 [internal] load .dockerignore
#4 [1/2] FROM docker.io/library/alpine:3.22@sha256:2e0b81d6...
#5 [2/2] RUN echo hello
#5 0.337 hello

Every step has a number (#5). Lines starting with #5 that also show a timestamp (0.337, seconds since the step started) are the step's own output. Two things are worth noticing. Steps are numbered in the order BuildKit created them, not the order they ran, and when two steps are independent they run at the same time. Also, CACHED appears on a step that was reused instead of executed, which is how you see the build cache from The Build Cache at work.

You can also make plain output the default with the environment variable BUILDKIT_PROGRESS=plain.

Cache mounts: keep downloads between builds

The normal build cache works per step: if a RUN pip install -r requirements.txt step has the same inputs, it is reused. But the moment requirements.txt changes by one line, the whole step runs again and pip downloads everything again.

A cache mount gives a step a directory that survives between builds, but is not part of the image. Package managers use it as their download cache.

DOCKERFILE
FROM python:3-slim
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

First build, with requests only:

CONSOLE
$ docker build --progress=plain -t tcd-pip .
...
#8 6.141 Collecting requests==2.32.3 (from -r requirements.txt (line 1))
#8 6.496   Downloading requests-2.32.3-py3-none-any.whl.metadata (4.6 kB)
...
#8 8.554 Downloading requests-2.32.3-py3-none-any.whl (64 kB)

Now add rich to requirements.txt and build again. The step must re-run (the input changed), but look at what pip prints:

CONSOLE
$ docker build --progress=plain -t tcd-pip .
...
#8 4.620 Collecting requests==2.32.3 (from -r requirements.txt (line 1))
#8 4.625   Using cached requests-2.32.3-py3-none-any.whl.metadata (4.6 kB)
#8 5.076 Collecting rich (from -r requirements.txt (line 2))
#8 5.330   Downloading rich-15.0.0-py3-none-any.whl.metadata (18 kB)
...

Only the new packages were downloaded; requests and its dependencies came from the mounted cache (Using cached). The cache directory is not in the image: running du -sh /root/.cache in a container from this image fails because the folder does not exist, so your image does not grow.

To see the semantics without any package manager, use a counter file inside the cache mount:

DOCKERFILE
FROM alpine:3.22
RUN --mount=type=cache,target=/cache \
    n=$(cat /cache/count 2>/dev/null || echo 0); \
    echo $((n+1)) > /cache/count; \
    echo "cache use count: $((n+1))"

Build it, then change the text of the echo line before each rebuild (so the step re-runs instead of being CACHED):

CONSOLE
$ docker build --progress=plain -t tcd-counter .
#5 0.469 run A, cache use count: 2
$ docker build --progress=plain -t tcd-counter .
#5 0.475 run B, cache use count: 3
$ docker build --progress=plain -t tcd-counter .
#5 0.404 run C, cache use count: 4
$ docker build --progress=plain --no-cache -t tcd-counter .
#5 0.426 run C, cache use count: 1

The counter keeps growing from build to build (it started at 2 because I had already built an earlier version of this file once), which proves the directory survived. --no-cache gives the step a fresh, empty cache mount, so the counter starts again at 1; use it when you suspect a poisoned cache. The mount point is not part of the final filesystem, so ls /cache in a container from the image fails with "No such file or directory".

Typical targets for cache mounts:

Tool Mount target
pip /root/.cache/pip
npm /root/.npm
apt /var/cache/apt and /var/lib/apt (with sharing=locked)
Go modules and build cache /go/pkg/mod, /root/.cache/go-build
Maven /root/.m2
Cargo /usr/local/cargo/registry

Options you may need: id= (name the cache so several steps share it), sharing=shared|private|locked (what happens when two builds use the same cache at once; locked makes the second wait, which is right for apt) and uid=/gid=/mode= for permissions when the step runs as a non-root user.

Cache mounts live in the builder, not in the image or your project folder. A fresh CI runner or a freshly created builder starts with empty cache mounts. They speed up builds on a machine you keep; they do not travel with the image.

Secret mounts: use a secret without storing it

ENV and ARG showed that a token passed as a build argument ends up in docker history. A secret mount solves that: the value appears as a file (or environment variable) only while one RUN step executes, then disappears. It is never written to a layer.

DOCKERFILE
FROM alpine:3.22
RUN --mount=type=secret,id=api_token \
    echo "token has $(wc -c < /run/secrets/api_token) bytes" && \
    ls -l /run/secrets/
RUN ls /run/secrets 2>&1 || true

Create a secret file and pass it with --secret:

CONSOLE
$ printf 's3cr3t-token-value' > token.txt
$ docker build --progress=plain --secret id=api_token,src=token.txt -t tcd-secret .
...
#5 0.910 token has 18 bytes
#5 0.912 total 4
#5 0.912 -r--------    1 root     root            18 Oct 23 14:26 api_token
#6 0.178 ls: /run/secrets: No such file or directory

The first step saw a read-only file at /run/secrets/api_token. The very next step, with no --mount, saw nothing. Check that it did not leak:

CONSOLE
$ docker history tcd-secret --no-trunc --format '{{.CreatedBy}}'
RUN /bin/sh -c ls /run/secrets 2>&1 || true # buildkit
RUN /bin/sh -c echo "token has $(wc -c < /run/secrets/api_token) bytes" &&     ls -l /run/secrets/ # buildkit
CMD ["/bin/sh"]
ADD alpine-minirootfs-3.22.7-x86_64.tar.gz / # buildkit

The history shows the command, which mentions the file name, but not the value.

You can also take the secret from an environment variable on your machine, and expose it as a variable inside the step:

DOCKERFILE
FROM alpine:3.22
RUN --mount=type=secret,id=api_token,env=API_TOKEN \
    echo "token length: ${#API_TOKEN}"
CONSOLE
$ export MY_TOKEN=abcdef123
$ docker build --progress=plain --secret id=api_token,env=MY_TOKEN -t tcd-secret-env .
#5 0.633 token length: 9

Two behaviors professionals need to know:

  1. A missing secret is not an error by default. If you forget --secret, the file simply is not there and your command fails with its own confusing message (wc exited with code 1 in my test). Add required=true to the mount and BuildKit fails immediately with secret api_token: not found.
  2. The secret's value is not part of the cache key. I built the environment-variable example with a 9-character token, then again with a much longer one, and the second build printed CACHED: BuildKit did not re-run the step. If the output of a step depends on the secret's value, use --no-cache or change something else in the step.

A secret mount protects the image. It cannot stop your own command from writing the secret somewhere in the filesystem (for example cat /run/secrets/api_token > /app/.env). Use it to authenticate a download or package install, and never copy the value into a layer. See Managing Secrets for the full picture.

SSH mounts: private repositories without keys in the image

If a build must clone a private Git repository, do not COPY your private key into the image. An SSH mount forwards your local SSH agent into a single step:

DOCKERFILE
FROM alpine:3.22
RUN apk add --no-cache git openssh-client
RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts
RUN --mount=type=ssh git clone [email protected]:example/private-repo.git /src
CONSOLE
$ docker build --ssh default -t app .

This is a read-only example: it needs a real repository and a running SSH agent. The key point is that the agent socket is mounted for that one step, and the private key never enters the build. Without the agent, the step simply sees no socket; in my test ls "$SSH_AUTH_SOCK" failed with exit code 1 when I did not pass --ssh.

Heredocs: readable scripts in a Dockerfile

Long RUN commands joined with && \ are fragile. BuildKit supports heredocs, so a multi-line script is written as a script:

DOCKERFILE
FROM alpine:3.22

RUN <<EOT
set -e
echo "step one"
echo "step two"
mkdir -p /app
EOT

COPY <<EOT /app/config.ini
[server]
port = 8080
name = demo
EOT

CMD ["cat", "/app/config.ini"]
CONSOLE
$ docker build --progress=plain -t tcd-heredoc .
...
#6 [2/4] RUN <<EOT (set -e...)
#6 0.577 step one
#6 0.577 step two
#7 [3/4] COPY <<EOT /app/config.ini
...
$ docker run --rm tcd-heredoc
[server]
port = 8080
name = demo

The RUN heredoc becomes one layer, and COPY <<EOT /path creates a small file inline without needing it in your build context. You can pick another interpreter with a shebang as the first line (#!/bin/sh -eu worked in my test), or write RUN <<EOT python3 when the image has Python.

Watch out for one trap: a heredoc script does not stop at the first failing command unless you say so. This script ended with false in the middle:

DOCKERFILE
FROM alpine:3.22
RUN <<EOT
echo one
false
echo never printed
EOT
CONSOLE
$ docker build --progress=plain -t tcd-heredoc2 .
#6 0.434 one
#6 0.434 never printed

The build succeeded and printed the line that its name claims it would not. Start the script with set -e (or use the -e shebang) and the same file fails at false with exit code 1, as you would expect.

Build checks: lint your Dockerfile

BuildKit can analyze a Dockerfile without building it. Take a deliberately old-fashioned file:

DOCKERFILE
FROM alpine
MAINTAINER me
ENV key value
COPY . /app
CMD echo hi
CONSOLE
$ docker build --check .
Check complete, 4 warnings have been found!

WARNING: MaintainerDeprecated - https://docs.docker.com/go/dockerfile/rule/maintainer-deprecated/
Maintainer instruction is deprecated in favor of using label
Dockerfile:2
...
WARNING: LegacyKeyValueFormat - https://docs.docker.com/go/dockerfile/rule/legacy-key-value-format/
"ENV key=value" should be used instead of legacy "ENV key value" format

The four rules that fired were MaintainerDeprecated, LegacyKeyValueFormat, SecretsUsedInArgOrEnv (the name key looks like a credential) and JSONArgsRecommended (the shell-form CMD). The same warnings also appear at the end of a normal build. Running --check in CI turns them into a gate. Dockerfile Best Practices shows how to fix each pattern.

Build outputs: images are not the only result

By default a build produces an image in Docker's store. With --output you can ask for something else. This is wonderful for build tools that should ship files, not an image:

DOCKERFILE
FROM alpine:3.22 AS build
RUN echo "hello artifact" > /result.txt

FROM scratch
COPY --from=build /result.txt /result.txt
CONSOLE
$ docker buildx build --output type=local,dest=./out .
#7 exporting to client directory
#7 copying files 48B 0.0s done
$ cat out/result.txt
hello artifact
$ docker buildx build --output type=tar,dest=out.tar .
$ tar tf out.tar
result.txt

type=local writes the final stage's filesystem to a folder, type=tar to an archive, and type=image/type=registry (shortened to --load and --push) deliver images. Combine this with a named stage and --target from Multi-Stage Builds to extract compiled binaries, test reports or generated documentation straight to your disk.

Bake: describe builds in a file

When a project builds several images or variants, repeating long buildx build commands gets old. A bake file describes the builds once:

HCL
group "default" {
  targets = ["english", "german"]
}

target "english" {
  tags = ["tcd-bake:en"]
}

target "german" {
  args = { GREETING = "hallo" }
  tags = ["tcd-bake:de"]
}

With a Dockerfile that has ARG GREETING=hello, save the file as docker-bake.hcl and run:

CONSOLE
$ docker buildx bake --print german
{
  "group": { "default": { "targets": [ "german" ] } },
  "target": {
    "german": {
      "context": ".",
      "dockerfile": "Dockerfile",
      "args": { "GREETING": "hallo" },
      "tags": [ "tcd-bake:de" ]
    }
  }
}
$ docker buildx bake
$ docker run --rm tcd-bake:en
hello
$ docker run --rm tcd-bake:de
hallo

(The --print output above is condensed; the real one is pretty-printed over more lines.) bake builds both targets in one invocation, in parallel, sharing whatever they can. It can also read a Compose file, which is handy in CI (Docker in CI).

A dedicated builder: more drivers, more cache backends

The default docker driver cannot export its cache to a folder or a registry. Create a builder that runs BuildKit in a container:

CONSOLE
$ docker buildx create --name tcd-builder --driver docker-container
tcd-builder
$ docker buildx inspect tcd-builder --bootstrap
#1 [internal] booting buildkit
#1 pulling image moby/buildkit:buildx-stable-1
#1 creating container buildx_buildkit_tcd-builder0
Name:          tcd-builder
Driver:        docker-container
...
Status:                running

Now a build can export its cache and a later build, on this machine or a clean CI runner, can import it:

CONSOLE
$ docker buildx build --builder tcd-builder --progress=plain \
    --cache-to type=local,dest=./cache,mode=max \
    --cache-from type=local,src=./cache --load -t tcd-cx .
...
#5 [2/2] RUN sleep 3 && echo "expensive work done" > /result.txt
#5 DONE 3.5s
#8 exporting cache to client directory
$ docker buildx build --builder tcd-builder ... (same command again)
#5 importing cache manifest from local:5261540413244535367
#6 [2/2] RUN sleep 3 && echo "expensive work done" > /result.txt
#6 CACHED

mode=max exports the cache of all stages, not only the final one. In real pipelines the cache backend is usually type=registry or type=gha. Build Performance compares them. When you are done with a builder, docker buildx rm tcd-builder deletes it and its container.

When to use what

You want to... Use
Speed up package installs when dependencies change RUN --mount=type=cache
Use a token or password during the build --secret + RUN --mount=type=secret
Clone a private repo --ssh + RUN --mount=type=ssh
Write a long script cleanly Heredoc
Get files, not an image --output type=local
Catch Dockerfile smells early docker build --check
Build many targets or platforms docker buildx bake
Share cache between machines A docker-container builder with --cache-to/--cache-from

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is the relationship between docker build and docker buildx build?

    BuildKit is the default engine and docker build is a shortcut for docker buildx build. buildx exposes the extra options such as --output, --cache-to and --platform.
  2. 2. You add one package to requirements.txt. Your RUN step uses --mount=type=cache,target=/root/.cache/pip. What happens?

    A changed input still invalidates the step, so it re-runs. The mount only provides a persistent directory, so unchanged packages say 'Using cached'. The directory is not part of the image.
  3. 3. Why is RUN --mount=type=secret,id=token ... safer than ARG TOKEN?

    A secret mount appears as a temporary file (or variable) during one RUN step. Build arguments, by contrast, are recorded in docker history.
  4. 4. A heredoc RUN <<EOT script contains a command that fails in the middle, followed by more commands. The build succeeds. What is the most likely fix?

    A shell script keeps going after a failing command unless you start it with set -e (or use a shebang with -e). The exit code of the last command decides whether the step fails.
  5. 5. How do you export only the files produced by a build to a local folder instead of creating an image?

    --output type=local writes the final stage's filesystem to a directory. Using FROM scratch as the last stage keeps only the files you copy into it.

Summary

  • BuildKit is the default build engine; docker build is a shortcut for docker buildx build, and --progress=plain shows the full numbered log.
  • RUN --mount=type=cache keeps a download or compile cache between builds without adding it to the image; it lives in the builder.
  • RUN --mount=type=secret gives one step a temporary file or variable and leaves no trace in layers or history. Add required=true, and remember the secret's value is not part of the cache key.
  • --ssh forwards your SSH agent for private clones; heredocs make multi-line RUN and inline COPY readable (start scripts with set -e).
  • docker build --check lints a Dockerfile; --output exports files or tarballs instead of an image; docker buildx bake describes many builds in one file.
  • A docker-container builder unlocks cache export and import for CI.

Next: Multi-Platform Images