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.

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
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
| Command | Stopped containers | Dangling images | Tagged unused images | Unused volumes | Build cache |
|---|---|---|---|---|---|
system prune | Yes | Yes | No | No | Dangling only |
system prune -a | Yes | Yes | Yes | No | All unused |
system prune --volumes | Yes | Yes | No | Yes | Dangling only |
container prune | Yes | No | No | No | No |
image prune | No | Yes | No | No | No |
image prune -a | No | Yes | Yes | No | No |
volume prune | No | No | No | Yes | No |
builder prune | No | No | No | No | Yes |
| Reclaim source | Typical size | Safe to remove |
|---|---|---|
| Build cache | Often the largest | Yes, rebuilt on next build |
| Dangling images | Medium | Yes, nothing references them |
| Stopped containers | Small, but many | Yes, unless you need their filesystem |
| Unused volumes | Can be huge | Check first — may hold data |
| Container logs | Can be huge | Not touched by any prune |
Practical edge cases and deep dives
1. Read docker system df -v first
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 recordRECLAIMABLE 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
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
docker buildx prune --filter until=168h --keep-storage 20GB
docker builder prune --keep-storage 10GB --filter until=72hBuildKit 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
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
sudo du -sh /var/lib/docker/* | sort -h | tail
docker logs --tail 1 <container> > /dev/nullContainer 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:
{
"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
# 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" -fThe 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 symptom | Cause | Fix |
|---|---|---|
Data gone after docker system prune --volumes | Unused volumes were deleted | Restore from backup; use labels and avoid --volumes |
image is being used by stopped container | Image referenced by a stopped container | Remove the container first, or use system prune |
| Prune freed far less than expected | Shared layers, or logs not counted | Check df -v; prune build cache; rotate logs |
no space left on device still after prune | Container logs, or /var/lib/docker inode exhaustion | Rotate logs; check df -i |
| Base images gone, next build slow | -a removed untagged base images | Accept it on CI; avoid -a on a dev machine |
| Cache always cold after pruning | builder prune removed everything | --keep-storage and --filter until |
docker system prune -f in a cron job deleted volumes | Script predates a change, or --volumes present | Read the actual flags; run dry runs first |
| Prune requires confirmation in a script | Missing -f with a TTY | -f in automation, never on a host with state |
| Registry or CI disk fills daily | No scheduled prune at all | Schedule one with filters and alerting |
| Volume prune touched an NFS/CIFS volume | Local driver volume unreferenced | Recreate; 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 toolsSmall utilities that fit Docker work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Docker guides
All Docker guidesDocker Inspect: Go Templates, Format Flags, and JSON Filtering
The fields worth knowing, the array-versus-object trap, and why <no value> silently passes your monitoring check instead of failing it.
Docker Restart Policies: no, on-failure, always, and unless-stopped
What each policy really restarts, why on-failure ignores a clean exit, how backoff hides crash loops, and why health checks never trigger a restart.
Docker Compose Profiles: Multi-Environment Configs and Overrides
Profiles select which services exist; override files change how they run. How the two fit together, and why ports concatenate instead of replacing.
Docker COPY vs ADD: Build Context, .dockerignore, and Cache Busting
ADD adds tar extraction and URLs nobody wants; COPY is the predictable choice. How the build context is packed, and how copy order decides rebuild time.
More in Docker
All Docker guidesThe guides filed next to this one in Docker, in library order.