Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Docker Cleanup: docker system prune, Dangling Images, and Reclaiming Disk Space

What each prune flag actually deletes, why -a removes your base images, and the log files that survive every prune.

~5 min readDocker
#Docker#Maintenance#Storage
3D illustration of vacuum cleaners clearing dangling stopped containers and orphaned cache layers into reclaimed disk space

Quick Summary

docker system prune deletes what nothing is using: stopped containers, dangling images, unused networks, and dangling build cache. It is the fastest way to recover disk on a build machine, and the fastest way to lose something you needed if you run it with the wrong flags. -a extends it to all unused images, --volumes extends it to unused volumes, and -f removes the only confirmation prompt.

The safer pattern is to prune by category with filters: docker container prune --filter until=24h, docker image prune -a --filter until=168h, docker builder prune --keep-storage 10GB. Category commands let you see what will go with docker system df and a dry run before anything is deleted.

Basic syntax and query signatures

bash
docker system df -v # what is using space, per object docker system prune # stopped containers, dangling images, unused networks docker system prune -a --volumes # everything unused, including images and volumes docker container prune --filter until=24h docker image prune -a --filter "until=168h" --filter "label!=keep=true" docker builder prune --filter until=72h --keep-storage 10GB docker volume prune --filter "label!=keep=true"

docker system prune without flags is the conservative version: it does not touch images that have a tag and are not referenced only as <none>, and it does not touch volumes at all. -a removes every image not used by a container, which includes the base images you pulled an hour ago, and --volumes removes named volumes that no container references — the data, not just the space.

Key comparison table

CommandStopped containersDangling imagesTagged unused imagesUnused volumesBuild cache
system pruneYesYesNoNoDangling only
system prune -aYesYesYesNoAll unused
system prune --volumesYesYesNoYesDangling only
container pruneYesNoNoNoNo
image pruneNoYesNoNoNo
image prune -aNoYesYesNoNo
volume pruneNoNoNoYesNo
builder pruneNoNoNoNoYes
Reclaim sourceTypical sizeSafe to remove
Build cacheOften the largestYes, rebuilt on next build
Dangling imagesMediumYes, nothing references them
Stopped containersSmall, but manyYes, unless you need their filesystem
Unused volumesCan be hugeCheck first — may hold data
Container logsCan be hugeNot touched by any prune

Practical edge cases and deep dives

1. Read docker system df -v first

bash
docker system df # TYPE TOTAL ACTIVE SIZE RECLAIMABLE # Images 148 12 42.1GB 36.4GB (86%) # Containers 31 4 1.2GB 1.1GB (91%) # Local Volumes 19 6 8.7GB 6.9GB (79%) # Build Cache 412 0 11.3GB 11.3GB docker system df -v # per image, per volume, per build-cache record

RECLAIMABLE is an estimate: shared layers between images mean removing one image frees less than its listed size, which is why a prune that deletes 30 GB of images sometimes returns 8 GB of disk. -v lists the individual items, which is the only way to notice that one 6 GB volume belongs to a database you still need.

2. -a and the base images

bash
docker image prune -a # WARNING! This will remove all images without at least one container associated to them.

Any image without a container — running or stopped — counts as unused. That includes the node:22 base image, the postgres:17 you pulled for a debugging session, and every intermediate tag from your own builds. On a developer laptop, that means the next build re-pulls everything; on a CI runner, it is usually exactly what you want.

Images referenced by a stopped container are protected until the container is removed. That ordering is why docker system prune -a removes containers first and images second in one pass, and why docker image prune -a alone can free less than expected after a docker run left containers behind.

3. Build cache is the largest and the safest

bash
docker buildx prune --filter until=168h --keep-storage 20GB docker builder prune --keep-storage 10GB --filter until=72h

BuildKit keeps every intermediate layer, including layers from cancelled builds and from branches you merged weeks ago. --keep-storage prunes until the cache is under the given size, oldest first; --filter until=... protects anything recent, which matters on a machine where the next build should still hit the cache.

A cache mount (--mount=type=cache) lives outside the layer cache and is not removed by image pruning — it is kept in the builder's cache directory and removed by builder prune. That is why a machine can have 40 GB of "build cache" with no images to show for it.

4. Volumes: prune is data deletion

bash
docker volume ls -qf dangling=true # preview what would go docker volume prune --filter "label!=keep=true"

docker volume prune removes volumes not referenced by any container. An anonymous volume from docker run -v /data becomes unreferenced the moment its container is removed, so a routine prune silently deletes it — including a database's data directory if the volume was created that way. Named volumes declared in Compose are also removed when they are not attached to a running or stopped container, which is the case after docker compose down.

Label the volumes you care about and filter on the label; or skip volume pruning entirely and handle volumes explicitly, one name at a time, after a backup.

5. The space that survives every prune

bash
sudo du -sh /var/lib/docker/* | sort -h | tail docker logs --tail 1 <container> > /dev/null

Container log files (/var/lib/docker/containers/<id>/<id>-json.log) are not images, volumes, or containers, so no prune touches them. A service that logs verbosely can produce tens of gigabytes and still show a clean docker system df. Configure rotation at the daemon level:

json
{ "log-driver": "json-file", "log-opts": { "max-size": "50m", "max-file": "5" } }

For Compose, the same settings go under logging.options per service, because the daemon default only applies to containers created after the change.

6. Scheduling it without breaking the next build

bash
# nightly at 03:20: keep a week of images, cap the builder cache 20 3 * * * docker image prune -a --filter "until=168h" -f \ && docker builder prune --keep-storage 15GB -f \ && docker container prune --filter "until=48h" -f

The script that runs unattended should never contain system prune --volumes. Keep the image window long enough to cover a rollback (until=168h keeps a week), cap the builder cache by size rather than by age so a quiet week does not empty it, and alert on df -h /var/lib/docker rather than on the prune's output — a prune that runs every night and still leaves 95% used is reporting success while the real growth is somewhere the prune cannot reach.

Common mistakes and runtime errors

Error or symptomCauseFix
Data gone after docker system prune --volumesUnused volumes were deletedRestore from backup; use labels and avoid --volumes
image is being used by stopped containerImage referenced by a stopped containerRemove the container first, or use system prune
Prune freed far less than expectedShared layers, or logs not countedCheck df -v; prune build cache; rotate logs
no space left on device still after pruneContainer logs, or /var/lib/docker inode exhaustionRotate logs; check df -i
Base images gone, next build slow-a removed untagged base imagesAccept it on CI; avoid -a on a dev machine
Cache always cold after pruningbuilder prune removed everything--keep-storage and --filter until
docker system prune -f in a cron job deleted volumesScript predates a change, or --volumes presentRead the actual flags; run dry runs first
Prune requires confirmation in a scriptMissing -f with a TTY-f in automation, never on a host with state
Registry or CI disk fills dailyNo scheduled prune at allSchedule one with filters and alerting
Volume prune touched an NFS/CIFS volumeLocal driver volume unreferencedRecreate; prefer explicit volumes in Compose

The habit that makes pruning safe: docker system df -v before, the category command instead of system prune, and --filter until=... on anything automated. The only prune that should ever include --volumes is the one on a machine whose volumes you can recreate from source control.

Try matching browser tools

All tools

Small utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Docker guides

More in Docker

All Docker guides

The guides filed next to this one in Docker, in library order.