Reclaim Docker Build Cache with docker builder prune

The disk is nearly full, the build cache is the fat one, and you want it gone without taking anything else with it. This guide covers docker builder prune, and how to check what is reclaimable before you approve the deletion. The examples were checked against Docker CE CLI 5:29.8.1-1~ubuntu.24.04~noble, with Docker reporting version 29.8.1.

The route

Jump straight to the step you need, or tick off Done means at the end.

1. Check the installed command
2. Measure the cache before deleting it
3. Start with unused dangling cache
4. Limit cleanup by age
5. Use all and force only deliberately
6. Treat storage limits as version-specific
7. Verify the cleanup

Allow about ten minutes for a one-off cleanup. You need a shell and access to the Docker daemon. The first checks are ordinary, read-only commands.

The prune is destructive. It removes cache entries and no Docker command restores them.
What it leaves alone. It does not normally remove tagged images, containers or volumes.
The cost. A later build may need to download or recreate the layers you delete.

1. Check the installed command

Start by confirming the binary, package and command syntax. These checks do not change Docker state and do not need elevated privileges when your account can already use the daemon:

$ command -v docker
/usr/bin/docker
$ docker --version
Docker version 29.8.1, build 4a63305
$ dpkg-query -W -f='${Package} ${Version}\n' docker-ce-cli
docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble
$ docker builder prune --help
Usage:  docker buildx prune

Remove build cache

Spot the oddity: docker builder prune prints help for the Buildx prune implementation. That is version-specific and worth noting.

The installed help exposes Buildx options such as --max-used-space.
The local docker-builder-prune(1) manpage documents the common builder-prune interface, including --all, --filter, --force and --keep-storage.

Always check the help from the Docker installation you are about to operate.

Checkpoint

If docker builder prune --help fails, stop here. Fix the Docker CLI or Buildx installation first. Do not copy a cleanup command from another host and assume that its options exist locally.

2. Measure the cache before deleting it

Use Docker's disk-usage report to see the current build-cache size and its reclaimable portion:

$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          32        28        14.79GB   36.76MB (0%)
Containers      48        48        216.7MB   0B (0%)
Local Volumes   17        5         12.22GB   11.93GB (97%)
Build Cache     125       0         5.974GB   5.926GB

Your counts and sizes will differ. Look at the Build Cache row only. Do not confuse reclaimable volumes with build cache: docker builder prune is not a volume-cleanup command, and docker system prune has a wider scope.

Tip

Let running builds finish before you prune. A cache entry used by a build may not be reclaimable in the same way as an old, unused entry. If a shared builder is busy, arrange a maintenance window or ask the build owner before continuing.

3. Start with unused dangling cache

The safest default is the command with no extra selection flags. It targets unused build cache rather than asking for all unused cache:

$ docker builder prune
WARNING! This will remove all dangling build cache. Are you sure you want to continue? [y/N]

Not sure? Say no. Press n or Ctrl-C if the proposed cleanup is not clearly acceptable.
Sure? Say yes. Type y only after checking the daemon and the maintenance window.
Expect a report. Output normally lists the cache records removed and the reclaimed space; the exact records and totals depend on the host.

Warning

This command changes state and cannot be undone. The practical recovery is to rebuild, so keep source trees, lock files and dependency credentials available so the next build can recreate what was removed.

4. Limit cleanup by age

For a scheduled or cautious manual cleanup, add the documented filter instead of deleting every currently unused entry. The manpage gives until=24h as its example:

$ docker builder prune --filter 'until=24h'
WARNING! This will remove all dangling build cache. Are you sure you want to continue? [y/N]

The shell quotes keep the filter as one argument. The filter is a selection boundary, not a preview: the command still asks for confirmation and still removes matching cache when you answer y.

Tip

Use only an age value that the help on your installed CLI supports. A longer age preserves more warm cache but usually reclaims less space.

5. Use all and force only deliberately

--all widens the operation from dangling cache to all unused build cache. That can remove useful intermediate layers that are not currently attached to a build, so use it only when the rebuild cost is acceptable:

$ docker builder prune --all --filter 'until=168h'
WARNING! This will remove all unused build cache. Are you sure you want to continue? [y/N]

--force removes the confirmation prompt. It is appropriate only when the selection has already been reviewed and the command is protected by your own scheduling and logging.

Warning

Do not combine --force with --all in a copied one-liner unless you have deliberately accepted the wider deletion.

$ docker builder prune --all --filter 'until=168h' --force
Deleted build cache objects and reclaimed space are reported by Docker.

In scripts, record the host, Docker version, filter and exit status. Treat a non-zero exit status as a failed cleanup, not as proof that the cache is empty. Run docker system df again afterwards to check the result.

6. Treat storage limits as version-specific

The installed manpage lists --keep-storage for the amount of disk space to keep. The Docker 29.8.1 help shown above instead exposes Buildx-specific storage controls such as --max-used-space, --min-free-space and --reserved-space. Do not substitute one for the other without checking the exact help output and testing the command on a non-critical builder.

This matters in automation. A command accepted by a newer Buildx plugin may fail on a host using only the manpage's interface, and a command copied from an older guide may not express the limit you intended.

Tip

When in doubt, use an explicit age filter, keep the confirmation prompt, and verify the resulting disk report.

7. Verify the cleanup

After a successful prune, repeat the read-only disk report:

$ docker system df
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          32        28        14.79GB   36.76MB (0%)
Containers      48        48        216.7MB   0B (0%)
Local Volumes   17        5         12.22GB   11.93GB (97%)
Build Cache     42        0         1.103GB   1.054GB

Checkpoint

The example is illustrative, so your totals will not match it. The build-cache row should have changed in the direction you expected, and the Docker service and active builds should still be healthy.

A following build may be slower. Cache misses are expected after pruning.

Done means

Version confirmed. You confirmed the Docker CE CLI version and inspected the local prune help.
Measured first. You measured build cache before deleting anything.
Scope chosen. You used the default dangling-cache scope or explicitly accepted a wider --all scope.
Age filter used. You added one when preserving recent cache mattered.
Risky flags treated as deliberate. --force and storage-limit flags were version-specific choices, not copy-and-paste.
Result checked. You reran docker system df and accepted that deleted cache can only be recreated by later builds.