How Big Can Docker Build Cache Get? Mine Reached Almost 30 GB

I only wanted to start AVN Documentation AI locally, but instead of a normal Docker troubleshooting session I found a much more interesting problem: the machine was almost out of disk space.

The filesystem reached 99-100% usage, with only about 1.4-3.5 GB free in some of the snapshots I captured.

When I checked Docker storage, the number that surprised me most was Build Cache: almost 29 GB.

The problem did not arrive as a Docker error saying that the cache was too large.

I saw a normal operating-system symptom: the filesystem was almost full.

So my first step was measurement, not pruning.

Later, available space dropped even further to roughly 1.4 GB and filesystem usage reached 100%.

At that point, randomly deleting project files would have been the wrong move. I first needed to understand what was actually consuming the disk.

This output changed the direction of the investigation immediately.

Volumes were only around 1 GB, so they were clearly not the main issue.

Images occupied more than 31 GB, but the unexpected number was almost 29 GB of Build Cache.

Until then, I thought of Docker build cache as temporary storage that would stay relatively small.

In reality, BuildKit keeps layers and build records across many builds so future builds can reuse previous work.

When Docker is used every day across several projects, that cache can quietly grow into tens of gigabytes.

I did not want to start with the most aggressive cleanup possible.

My first attempt targeted unused build cache conservatively.

The result was much smaller than I expected.

Build Cache still remained at roughly 28.33 GB, with about 16.85 GB still reported as reclaimable.

docker builder prune is conservative by default and targets dangling build cache.

A significant amount of unused cache can still remain available for reuse.

So the command can complete successfully while tens of gigabytes still remain on disk.

Before the next cleanup, the system had already reached a critical state.

One captured snapshot showed about 1.4 GB free while Build Cache had grown to roughly 29.22 GB.

I decided to use -a, but I still did not want to destroy every reusable cache record without a boundary.

Build Cache dropped from about 29.22 GB to 11.59 GB.

That is roughly 17.6 GB of build cache no longer occupying the disk.

The filesystem moved from a critical 1.4 GB free to about 24 GB available in the confirmed snapshot.

• Every Docker build can create new reusable layers.
• Changes to a Dockerfile or build context can invalidate previous layers.
• Dependency installation often creates large cached build stages.
• Working across several projects accumulates cache for different build graphs.
• Multi-stage builds can retain cache for intermediate stages.
• BuildKit intentionally trades disk space for faster future builds.

The cache itself is not a bug. Its purpose is to prevent Docker from repeating the same work during every build.

The problem begins when the disk cost of the cache becomes larger than the value of the build acceleration.

I discovered the issue while starting AVN Documentation AI, but it would be inaccurate to say that this project alone created all 29 GB.

The machine already contained other Docker and Laradock environments, several PHP runtimes, images, and previous builds.

The new AI workflow simply pushed disk usage far enough for the accumulated cache to become impossible to ignore.

This is why I did not begin with docker system prune.

Once docker system df shows that Build Cache is the main candidate, I prefer cleaning the specific resource type instead of everything at once.

• Do not run docker system prune -a automatically before checking docker system df.
• Do not delete volumes without checking what they contain.
• Do not assume images are always the largest Docker consumer.
• Do not treat a successful builder prune as proof that the cache is now small.
• Do not clear cache immediately before an important build if there is no time to restore dependencies.
• Do not confuse Docker build cache with model cache or application cache.

Reclaiming more than 17 GB looks like a free win, but the cache existed for a reason.

After an aggressive prune, the next build may repeat dependency installation, compilation, or layer downloads.

I traded disk space for a potentially slower cold build. With the filesystem at 100%, that was the right trade-off.

Docker was not the only cache on the machine.

The local AI environment also had a separate model cache of roughly 2.3 GB.

This reinforced another lesson: Docker cache, model cache, and project data need to be measured separately instead of calling all of them "Docker disk usage".

I had already been using Docker heavily through Laradock, multiple PHP runtimes, and private Composer dependencies.

I have written separately about my multi-PHP Laradock workflow and about Composer, GitLab, and Docker SSH agent.

This incident added one more routine check to that workflow: Docker disk usage.

• Start with filesystem usage using df -h.
• Inspect Docker storage with docker system df.
• Identify whether images, build cache, or volumes are actually growing.
• Start with the narrowest cleanup command.
• Use -a only when its scope is understood.
• When possible, limit aggressive cleanup with an age filter.
• After cleanup, run both df -h and docker system df again.
• Remember that clearing cache can make the next build slower.

• Do not wait for 99% disk usage before checking docker system df.
• Treat Build Cache as a real disk-space consumer.
• Do not confuse reclaimable with automatically safe-to-delete.
• Clean a specific Docker resource when the cause is already known.
• Do not touch volumes without a separate check.
• Expect a slower cold build after aggressive pruning.
• Monitor AI model caches and other non-Docker caches separately.

Docker Build Cache can absolutely grow into tens of gigabytes.

In my case it approached 30 GB while the filesystem was already sitting at the edge of 100% usage.

docker system df helped me separate build cache from images and volumes, and a controlled docker builder prune -a --filter "until=168h" removed roughly 17.6 GB of old unused cache.

The most important lesson for me is not to start Docker cleanup by deleting things. Measure first, identify the resource type, and only then clean the thing that is actually causing the problem.