Dash0 Raises $110M Series B at $1B Valuation

  • 6 min read

How to Clear Docker Build Cache

Your build just died with no space left on device, and the build cache is almost always the culprit. BuildKit caches every build step so rebuilds are fast, but it grows without bound and Docker never cleans it up. On an active dev machine or CI runner, 15–30 GB of build cache is normal.

This article covers how to inspect and prune the build cache specifically. If you need to clean up images, containers, and volumes too, see How to clean up Docker disk space.

Find out how much cache you have

Run docker system df to see a breakdown by object type:

bash
1
docker system df
text
12345
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          45        12        18.5GB    12.3GB (66%)
Containers      23        3         2.1GB     1.9GB (90%)
Local Volumes   12        5         5.2GB     3.1GB (59%)
Build Cache     668       0         15.72GB   15.72GB

The RECLAIMABLE column is the one that matters. Build cache at 100% reclaimable is typical because nothing holds a reference to old cache entries once the image exists.

For a more granular view, docker buildx du lists individual cache records with their sizes and last-accessed timestamps. It's the better tool when you want to understand what's worth pruning before you wipe everything.

bash
1
docker buildx du

Prune the build cache

The default prune removes only dangling cache, meaning records that nothing currently references:

bash
1
docker buildx prune
text
12
WARNING! This will remove all dangling build cache. Are you sure you want to continue? [y/N] y
Total reclaimed space: 9.4GB

To wipe all unused build cache, including cache for images you still have locally, add -a:

bash
1
docker buildx prune -a -f

The -f skips the confirmation prompt, which is what you want in a script. After an -a prune your next build starts cold, so only use this flag when you actually need the space back.

You'll see docker builder prune referenced in older articles and Stack Overflow answers. On any recent Docker install it does the same thing, because it delegates to BuildKit through buildx. If you ever see a DEPRECATED: The legacy builder is deprecated warning, that's the old non-BuildKit path, and the fix is to use docker buildx prune directly.

Prune by age

On CI, you usually want to keep recent cache but drop anything stale. The --filter flag handles this:

bash
1
docker buildx prune --filter "until=168h" -f

That removes build cache older than 168 hours (seven days). A weekly cron job running that command keeps most machines healthy without ever hitting no space left on device.

Set a cache budget

If you want to cap how much cache sticks around rather than pruning by age, use --reserved-space:

bash
1
docker buildx prune --reserved-space 5gb -f

This prunes the least recently used cache records until the remaining cache is down to 5 GB.

Two related flags exist for more fine-grained control. --max-used-space sets a hard ceiling on total cache size, and --min-free-space tells Docker to keep pruning until a target amount of free disk is available. You can combine them.

The --keep-storage deprecation

For years the standard advice was docker buildx prune --keep-storage 5g. That flag is deprecated. Running it on recent Docker versions prints a confusing notice pointing you to --max-storage, a name that was used internally but never shipped in a release. The actual replacement is --reserved-space, along with --max-used-space and --min-free-space.

Nearly every article and cached Stack Overflow answer still shows --keep-storage. If you paste one into a CI pipeline, it either warns or fails depending on your Docker version. Reach for --reserved-space instead.

Bypass the cache for a single build

If your problem isn't disk space but a stale layer producing a wrong build, you don't need to prune anything. Build without the cache:

bash
1
docker build --no-cache -t myapp .

Add --pull to also force a fresh pull of the base image instead of reusing the local copy:

bash
1
docker build --no-cache --pull -t myapp .

Final thoughts

Start with docker system df to confirm the build cache is actually where your space went, then use docker buildx prune to clear it. For CI, --filter "until=168h" or --reserved-space keeps cache from growing without bound. And if you're migrating old scripts, swap --keep-storage for --reserved-space before it breaks on you.

Disk pressure is only one of the ways a containerized host degrades quietly. Dash0's infrastructure monitoring tracks container and host resource usage alongside real-time logs and distributed traces, so you can catch a disk filling up or a container thrashing before it takes a build down. Start a free trial to see your containers, hosts, and clusters in one view. No credit card required.