Part of: Docker disk space on Mac: Docker.raw, images and build cache explained (Docker)
The Docker build cache is safe to clear. It only saves time on later builds, and Docker rebuilds it as needed. The price is a slower next build, because every step runs again and base images may download again.
What the build cache is
When you build an image, Docker runs each step in your Dockerfile and saves the result as a layer. The next build reuses a layer if nothing it depends on has changed. Those saved layers are the build cache. They are stored inside Docker’s disk image on your Mac, so they count toward its size. The overview explains that disk image.
See how big it is
Two read-only commands show it:
docker system df
docker buildx duThe first shows Docker’s disk usage. On the Docker we tested, the output also showed a Build Cache row with a total and a reclaimable amount; that is our observation, not something the reference page states. docker buildx du is the command Docker’s reference documents for the build cache, and it lists individual cache entries with their size, whether they are reclaimable and when each was last used. On Colima we also ran docker builder du, a shorter form that gives the same kind of list; it is not in the docs page, so treat that as our observation. All of these are read-only.
The reference page for docker system df does not define “reclaimable”, so read it as a hint about what looks unused, not as a promise.
What the prune options do
Docker documents a build cache prune command under docker builder, with these options:
- All. Widens the scope from dangling cache to all unused build cache.
- Filter. Limits removal by a condition. The common example in the reference is an age such as
until=24h, which targets entries older than 24 hours. - Keep storage. Keeps a set amount of cache and removes the rest, so recent builds stay fast.
Docker’s pruning guide covers the same cache under the docker buildx command too, with a --builder option for a specific builder. A system prune also includes build cache, according to the same guide.
I did not run a prune while writing this, because pruning deletes data. Look at the reference for the exact syntax of your Docker version, and read the confirmation prompt.
Reading the list
The list from docker buildx du has four columns: an ID, a RECLAIMABLE flag, a SIZE and a LAST ACCESSED time. Entries marked reclaimable and not touched for days are the best candidates. Many small entries are normal: a single build can leave dozens of them.
Why does the cache grow at all? Each step in a Dockerfile can leave a layer. When you change a file early in the Dockerfile, every later step runs again and leaves new layers, while the old ones stay until something removes them. Builds you run often, or with changing dependencies, add up faster.
Safe, risky, never
| Item | Verdict | What breaks | Cost to recreate |
|---|---|---|---|
| Cache entries older than a few days | Safe | Nothing | Those layers rebuild on the next build that needs them |
| All unused build cache | Safe | The next build is slower | A longer build, plus re-downloaded base layers |
| Images or volumes, assuming a “cache” prune covers them | Not the same | A cache prune does not remove them. A full system prune can touch images and containers | Check the prompt before you confirm |
The cost of a cold build
After clearing, plan for:
- every Dockerfile step running again,
- base images and downloaded packages being fetched again, which depends on your connection,
- a slower first build per project, and normal speed after that.
On a machine with a fast connection and small projects you may barely notice. Large projects with many dependencies feel it most. If you build many times a day, prune by age rather than clearing everything, so recent layers stay.
A sensible routine
You do not need to clear the cache often. A simple habit is enough: look at the Build Cache row in docker system df now and then, and when it has grown past what you are comfortable with, prune the older entries and keep the recent ones. That way you pay the cost of a cold build once in a while, not every day.
If you build in a continuous integration system, remember that it has its own cache. Clearing the cache on your Mac does not touch it.
Does the space come back to the Mac?
Clearing the cache frees space inside Docker’s virtual disk. The file on your Mac may stay large, because it is a sparse disk image. Read the Docker.raw guide to compare the maximum size with the real one, and the reclaim guide for what to do if the file stays big.
How DiskJoy fits in
DiskJoy is our product. It is pre-alpha and it scans your Mac; the Docker build cache lives inside a virtual disk, which it sees as one file, not as separate entries. Cleanup is not built yet, so it does not remove anything. The download page shows the current status of the scan.
Frequently asked questions
Is it safe to clear the Docker build cache?
Yes. The cache only speeds up builds, and Docker rebuilds it when needed. The cost is that the next build is slower and may download base layers again.
How do I see how big the build cache is?
On the Docker we tested, docker system df also showed a Build Cache row with its size. docker buildx du, which Docker documents, lists the individual cache entries.
Does clearing the build cache free space on my Mac?
It frees space inside the Docker disk image. Whether the file on your Mac shrinks depends on your Docker tool and version, so check the real size with du afterwards.