19.3.1.5 Df Build Cache Usage

The build cache usage section within docker system df -v expands the Build Cache row from the default summary into a per-cache-entry breakdown. The Docker build system caches intermediate layers produced during docker build and docker buildx build operations so that subsequent builds can skip steps whose inputs have not changed. Over time, this cache can grow very large on active development machines or CI systems that build many images. The verbose view shows each cached entry individually, helping identify how much cache has accumulated and from what build steps.

Accessing the Build Cache Usage Section

docker system df -v

The build cache section appears after the volumes section in the verbose output.

Build Cache Usage Table Structure

Build cache usage: 1.1GB

CACHE ID          CACHE TYPE    SIZE      CREATED         LAST USED       USAGE     SHARED
abc123def456      regular       245MB     3 days ago      3 days ago      1         false
def456abc789      regular       187MB     5 days ago      3 days ago      2         false
789abc012def      regular       98MB      1 week ago      1 week ago      0         false
012def345abc      source.local  0B        2 days ago      2 days ago      1         false
345abc678def      exec.cachemount 512MB   1 day ago       1 day ago       3         false

Header Line

Before the table, the section shows the total build cache size as a single summary line:

Build cache usage: 1.1GB

This matches the SIZE value shown in the default docker system df output.

CACHE ID

A short identifier for the cache entry derived from the content hash of the cache record. Cache entries with the same inputs produce the same CACHE ID across builds, which is why Docker can skip re-running a step when nothing has changed.

CACHE TYPE

The type of cache entry, which corresponds to the kind of build step that produced it:

• regular: A standard build layer produced by a Dockerfile instruction such as RUN, COPY, or ADD. This is the most common type.
• source.local: A cache entry created from local build context files (the directory sent to the daemon at build time). These entries are usually very small because they only record the hash of the source files, not the files themselves.
• source.git: A cache entry from a Git repository used as the build context.
• exec.cachemount: A cache entry from a RUN --mount=type=cache instruction in a BuildKit Dockerfile. These can be very large because they store directories that persist across builds for things like package manager caches (apt, npm, pip).
• result: A cache entry for the final image or build output.

SIZE

The amount of disk space this particular cache entry occupies. A single exec.cachemount entry can be hundreds of megabytes or even gigabytes if it caches a large package manager directory. Regular layer entries vary in size depending on what the Dockerfile instruction installed or copied.

CREATED

When the cache entry was first created. Entries from weeks or months ago that have not been used recently are candidates for pruning.

LAST USED

When this cache entry was last referenced during a build. If LAST USED equals CREATED, the entry was used only in the build that created it and has not been reused since.

USAGE

How many times this cache entry has been referenced across all builds. An entry with USAGE = 0 was never actually used after being created — this can happen when a build was started but the step that would use this cache was never reached, or when the entry was invalidated before it could be used.

SHARED

Whether this cache entry is shared (referenced by multiple branches of the build graph). Shared entries are more expensive to prune because removing them may affect multiple dependent build steps.

How Build Cache Grows

On a development machine, the build cache grows with every docker build invocation that produces new layers. Common growth patterns:

• Each time you modify a package.json and rebuild, a new cache entry is created for the npm install step, while the old one becomes stale.
• Each change to source code that appears early in the Dockerfile invalidates all subsequent layer caches, generating new entries.
• Using RUN --mount=type=cache accumulates large cache directories that grow as packages are downloaded.

On CI systems, build cache can grow extremely fast because many builds run in quick succession, each potentially creating new cache entries.

Pruning the Build Cache

To remove all build cache:

docker builder prune

Docker asks for confirmation and then removes all cache entries that are not currently in use by an active build.

To skip the confirmation:

docker builder prune --force

To remove only cache entries older than a specific threshold:

docker builder prune --filter until=72h

This removes cache entries not used in the last 72 hours.

To remove all cache including entries currently in use (dangerous during active builds):

docker builder prune --all --force

Build cache is also removed as part of a full system cleanup:

docker system prune

Impact of Removing Build Cache

After clearing the build cache, the next docker build invocation must re-execute every step from scratch, downloading dependencies, compiling code, and running all RUN instructions again. This can make the first build after a prune significantly slower, especially for large projects with many dependencies.

On CI systems where each run is already a fresh environment, build cache typically does not survive between runs anyway (unless explicitly exported and imported), so pruning has no meaningful impact on build speed.

On development machines where fast iterative builds are important, selective pruning (by age or USAGE count) is better than clearing all cache at once.