BuildKit Cache and Mounts

How BuildKit decides a step is CACHED, what cache mounts and secret mounts add, and how to export the cache or find where the disk went.

The problem

Every CI run re-downloads the same packages, a rebuild after a one-line change takes ten minutes, and a private token has to reach `npm install` without ending up in an image layer. Meanwhile `docker image prune` frees nothing and the disk is still full because the build cache lives outside the image list. BuildKit has a precise rule for what counts as CACHED and three tools (cache mounts, secret mounts, exported caches) that cover these cases.

How it works

  • A step is CACHED when its cache key matches: for RUN the key is the parent layer plus the command text (plus ARG/ENV values visible to it); for COPY and ADD it is a checksum of the file contents. Observed: `touch f.txt` without changing the content left COPY and the following steps CACHED, and `RUN date +%s%N > /stamp` stayed CACHED forever because the command string never changed. BuildKit does not know a command is non-deterministic.
  • Invalidation cascades: a miss at step N reruns N and everything after it. Skip the cache with `--no-cache`, or per stage with `--no-cache-filter <stage>` (observed: only the named stage's RUN reran, and a later COPY that consumes its changed output reran as well). `--pull` re-resolves the base image tag.
  • `RUN --mount=type=cache,target=/var/cache/dl` mounts a directory that persists between builds and is not part of any layer. Observed: the counter file went from 0 to 1 across two builds even though the RUN had to rerun (BUST changed), and `ls /var/cache/dl` in the finished image failed with No such file or directory. Use it for package-manager download caches, compiler caches and the like.
  • A cache mount is identified by `id` (default: the target path), so two RUN steps with different targets can share one cache by giving the same `id` (observed: a file written at `/c` was visible at `/other`). `sharing=shared` (default), `private` or `locked` controls concurrent builds; `uid`, `gid` and `mode` set ownership (observed `owner=1000`). Treat the contents as disposable: the cache can be garbage-collected, and a fresh CI runner starts empty.
  • `RUN --mount=type=secret,id=tok` exposes the file `/run/secrets/tok` for that RUN only; supply it with `docker build --secret id=tok,src=tok.txt`. Observed: the RUN saw the file, the finished image had no `/run/secrets`. Unlike ARG, the value does not appear in the history line.
  • Cache can be exported and imported for CI: `--cache-to type=local,dest=DIR[,mode=max]` and `--cache-from type=local,src=DIR`, or `type=registry`, `type=gha`, `type=inline`. On this engine (Docker 29 with the containerd image store) `--cache-to type=local` worked on the default `docker` driver and wrote `blobs`, `index.json`, `oci-layout`. With the classic image store the `docker` driver typically rejects cache export and you need a builder with `--driver docker-container` (not tested here, as was importing the cache on a second builder). `mode=max` also exports intermediate stages; `mode=min` only the final ones.
  • The cache belongs to the builder, not to images. `docker image prune` and `docker rmi` do not touch it. `docker buildx du` lists the records (type such as `exec.cachemount`, size, usage count, last used); `docker builder prune` (optionally with `--filter until=24h`) or `docker buildx prune --max-used-space <size>` (older buildx: `--keep-storage`) trims it. They were not run here because this daemon is shared; the commands act on the whole builder.
  • `--progress=plain` prints every step with its output and a `CACHED` line for hits, and it is the quickest way to see where a cache miss starts. Combine with the next entry: the order of instructions decides how much of the cache survives a change.

Examples

A cache mount survives a rerun of its RUN and never lands in the image.

bash
cat > Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM alpine:3.20
ARG BUST=0
RUN --mount=type=cache,id=demo-dl,target=/var/cache/dl,sharing=locked \
    n=$(cat /var/cache/dl/count 2>/dev/null || echo 0); \
    echo $((n+1)) > /var/cache/dl/count; \
    echo "builds that used this cache before: $n"; \
    echo "$BUST" > /out
EOF
docker build --progress=plain --build-arg BUST=1 -t demo-bk . 2>&1 | grep 'builds that used'
docker build --progress=plain --build-arg BUST=2 -t demo-bk . 2>&1 | grep 'builds that used'   # RUN reruns, cache dir survives
docker run --rm demo-bk ls /var/cache/dl    # No such file or directory: the mount is not in the image

A secret mount is readable during one RUN and absent from the result.

bash
echo 's3cret' > tok.txt
cat > Dockerfile <<'EOF'
FROM alpine:3.20
RUN --mount=type=secret,id=tok test -s /run/secrets/tok && echo "secret visible during this RUN only"
EOF
docker build --progress=plain --secret id=tok,src=tok.txt -t demo-sec . 2>&1 | grep 'secret visible'
docker run --rm demo-sec ls /run/secrets      # No such file or directory

Bypass the cache for one stage, export the cache, and list the build cache records.

bash
cat > Dockerfile <<'EOF'
FROM alpine:3.20 AS deps
RUN date +%s > /stamp
FROM alpine:3.20
COPY --from=deps /stamp /stamp
EOF
docker build -q -t demo-nc .
sleep 2
docker build --progress=plain --no-cache-filter deps -t demo-nc . 2>&1 | grep -E 'deps 2/2|CACHED'   # the deps RUN reruns, and the COPY that consumes its new output reruns too

# export the build cache to a directory (works on this engine; see mechanisms for the driver caveat)
docker build -q --cache-to type=local,dest=/tmp/demo-cache,mode=max -t demo-nc .
ls /tmp/demo-cache                  # blobs  index.json  oci-layout (and a temporary ingest dir)
docker buildx du | head -5             # build cache records, by ID, size and last use

In practice

  • BuildKit — The default builder in Docker Engine; a `# syntax=docker/dockerfile:1` first line pins the Dockerfile frontend version, which decides which `RUN --mount` options and `--check` rules exist.
  • docker/build-push-action with GitHub Actions cache — Typically uses `cache-from: type=gha` and `cache-to: type=gha,mode=max` so a fresh runner can reuse layers from earlier runs.
  • pip, npm, Go modules, apt — Common cache mount targets such as `/root/.cache/pip`, `/root/.npm`, `/go/pkg/mod` and `/var/cache/apt`, so a changed manifest downloads only the new packages.
  • docker buildx — The CLI plugin that exposes `du`, `prune`, `bake`, `imagetools` and builder management for BuildKit.

Trade-offs

Pros

  • Cache mounts make dependency changes download only what is new, without bloating layers
  • Secret mounts keep credentials out of layers, history and cache keys
  • Exported caches let ephemeral CI runners start warm
  • `CACHED` and `--check` output make build behavior inspectable

Cons

  • Builds can depend on state that is not in the Dockerfile, so a cold cache may behave differently from a warm one
  • Cache grows silently outside the image list and needs explicit pruning
  • Exporting with `mode=max` can be large and slow to upload, and may need a non-default builder driver
  • Commands with side effects (apt-get update, date, curl) are cached by text, so stale results persist

See also (other cheatsheets)

← All Docker entries