A container image is built from layers, and every layer’s final content becomes part of the shipped artifact. Historically, this created an awkward tension. If a RUN npm install or RUN pip install step downloaded packages into a cache directory to speed up future installs, that cache directory became part of the layer — permanently baked into the image, adding tens or hundreds of megabytes that no running application ever actually needed. The common workaround was to explicitly clear the package manager’s cache at the end of the same RUN instruction, which kept the image lean but meant every single build, even an unrelated one on the same machine, had to re-download everything from the internet all over again.

BuildKit — the graph-based build engine that became Docker’s default builder — solved this with a dedicated mount type built specifically for this purpose: RUN --mount=type=cache,target=/some/path. This tells BuildKit to attach a persistent, reusable directory to that specific point in the container’s filesystem for the duration of the command only, then detach it again before the resulting layer is captured — so the directory’s contents genuinely persist across builds, while never being written into any layer at all.

graph TB
    A["Dockerfile RUN instruction\nwith --mount=type=cache"] --> B["BuildKit Solver"]
    B --> C["Cache Mount Manager"]
    C -->|"Looks up cache id"| D["Named Cache Volume\n(persists on build host)"]
    D -->|"Attached read-write"| E["Executor\n(runs the command)"]
    E -->|"Command finishes"| F["Cache directory detached"]
    E -->|"Only non-cache filesystem changes"| G["Snapshotter\n(captures the real layer)"]
    G --> H["Final Image Layer\n(cache contents excluded)"]
    D -->|"Reused next build"| C
    

The Named Cache Volume

Behind the scenes, BuildKit maintains its own pool of persistent storage volumes on the build host (or build worker, in distributed setups), completely separate from the ordinary image layer cache. Each of these volumes is identified by a cache ID — either one explicitly given by the Dockerfile author, or an automatically derived default tied to the mount’s target path. This is the actual “pantry shelf” that survives from one build to the next.

The Cache Mount Manager

When the solver reaches a graph node declaring a cache mount, a dedicated manager component resolves the cache ID to its named volume, attaches that volume at the requested target path inside the executor’s isolated filesystem, and enforces whichever sharing mode was requested if multiple builds try to use the same cache concurrently.

The Snapshotter’s Blind Spot (By Design)

Once the command finishes, BuildKit detaches the cache mount before asking the snapshotter to record what changed in the container’s real filesystem. Because the cache directory was never part of that real filesystem tree from the snapshotter’s point of view — it was a separate mount stacked temporarily on top — nothing inside it is captured into the resulting layer. This is the specific architectural trick that keeps caches fast without keeping them in the shipped image.

Cache mounts support three sharing modes, and choosing the right one matters once more than one build might use the same cache at the same time — which happens constantly on a busy CI cluster building several branches in parallel.

Shared (the default)

Multiple concurrent build steps can read and write the same cache volume at the same time, with no locking. This works well for tools designed to tolerate concurrent access to their own cache directory, such as many package managers’ download caches, where two processes writing different package files rarely conflict.

Private

Each concurrent build gets its own separate, temporary copy of the cache rather than sharing one volume live. This trades away some cross-build reuse for guaranteed isolation, useful when a tool’s cache format is not safe under concurrent writes.

Locked

Concurrent builds needing the same cache ID queue up and take turns, one at a time, guaranteeing exclusive access without the memory overhead of fully copying the cache per build. This suits caches that are large, expensive to duplicate, and used by tools that would corrupt their own state under true concurrent writes.

Internally, the cache ID is also part of what feeds into BuildKit’s broader content-addressable caching model, but it is tracked and stored as its own distinct namespace of volumes, separate from the layer-result cache discussed in general BuildKit architecture — the two caching systems solve different problems and are easy to conflate at first.

Because cache mount contents are explicitly excluded from image layers, they cannot accidentally leak into a shipped image the way a forgotten package manager cache directory once could — this closes a minor but real historical source of images unintentionally including stale, unreviewed dependency archives.

However, a cache volume is still a long-lived piece of state sitting on the build host or build cluster, and it deserves its own security thinking. A cache shared across many different projects (via a common cache id) means a compromised or malicious build step could in principle poison a cache directory that a completely different, later build then trusts implicitly. Using distinct, narrowly scoped cache ids per project, and periodically pruning caches, limits the blast radius of this kind of cross-build contamination.

BuildKit reports cache mount activity as part of its normal structured build progress output, and buildx’s du and prune subcommands surface how much disk space named caches are consuming on a given build host, letting platform teams monitor cache growth over time rather than discovering a full disk unexpectedly during a build.

On centralized, shared build clusters, buildkitd’s Prometheus-compatible metrics endpoint can be scraped to track cache hit effectiveness over time, giving platform teams a way to see whether cache mounts are genuinely paying off in aggregate build-time reduction across every team relying on the shared builder.

Pattern: One Cache ID Per Package Ecosystem

Giving each language ecosystem’s cache directory (npm, pip, Go modules, Maven) its own explicit, descriptive cache id keeps caches cleanly separated, makes disk usage easy to reason about per tool, and avoids one large tool’s cache crowding out another’s under shared storage limits.

Pattern: Locked Mode for Large, Fragile Caches

For a cache directory belonging to a tool known to misbehave under concurrent writes — some compiler or dependency-resolution caches fall into this category — deliberately choosing locked sharing mode trades a small amount of build queuing time for guaranteed correctness.

Anti-pattern: Treating a Cache Mount as Guaranteed to Exist

Writing a Dockerfile that assumes the cache mount will always contain something useful breaks on a brand-new build host with an empty cache, or a CI runner that never persists build host state between jobs. Correct usage always tolerates a cold, empty cache gracefully — cache mounts are an optimization, not a dependency.

Anti-pattern: One Giant Shared Cache Id for Everything

Reusing a single, generic cache id across every project and every tool defeats the purpose of scoping — unrelated projects end up fighting over the same volume, and pruning or debugging one project’s cache growth becomes impossible to isolate from another’s.