{"id":46,"date":"2026-07-31T22:52:19","date_gmt":"2026-07-31T19:52:19","guid":{"rendered":"https:\/\/john-nessime.com\/blog\/?p=46"},"modified":"2026-07-31T22:52:21","modified_gmt":"2026-07-31T19:52:21","slug":"docker-disk-usage-cleanup","status":"publish","type":"post","link":"https:\/\/john-nessime.com\/blog\/devops\/docker-disk-usage-cleanup\/","title":{"rendered":"Cleaning Up Docker Disk Usage Safely"},"content":{"rendered":"\n

The alert says the root partition is at 97%. You SSH in, run df -h<\/code>, and \/var\/lib\/docker<\/code> is sitting on forty-something gigabytes. The first search result tells you to run docker system prune -a --volumes<\/code>, and it will absolutely free the space. It will also delete the volume holding your Postgres data.<\/p>\n\n\n\n

Docker disk usage grows quietly because every part of it accumulates independently \u2014 images, stopped containers, volumes, build cache, and container logs, which are the one nobody expects and which no Docker command reports on. Cleaning it up is easy. Cleaning it up without destroying something takes about five more minutes.<\/p>\n\n\n\n

This is the order I work through it: measure first, reclaim from safest to most destructive, then fix the thing that caused the growth so you are not back here next month.<\/p>\n\n\n\n

Measure before you delete<\/h2>\n\n\n\n

Every cleanup starts here, and skipping it is how people delete the wrong thing:<\/p>\n\n\n\n

docker system df<\/code><\/pre>\n\n\n\n
That gives you four rows \u2014 Images, Containers, Local Volumes, Build Cache \u2014 with a total size and a reclaimable figure for each. The reclaimable column is the one that matters. If build cache is eleven gigabytes and all of it is reclaimable, you have found your win and you never need to go near volumes.<\/p>\n\n\n\n
For the itemised version:<\/p>\n\n\n\n
docker system df -v<\/code><\/pre>\n\n\n\n
Now you can see individual images with their sizes, which containers are using what, and which volumes have no container attached. Read this before running anything destructive.<\/p>\n\n\n\n
Two more views worth having open:<\/p>\n\n\n\n
# What is actually running, and what is just sitting there stopped\ndocker ps -a --format 'table {{.Names}}t{{.Image}}t{{.Status}}t{{.Size}}'\n\n# Images by age, oldest first\ndocker images --format 'table {{.Repository}}:{{.Tag}}t{{.Size}}t{{.CreatedSince}}'<\/code><\/pre>\n\n\n\n
\n\n\n\n
Reclaim in order, safest first<\/h2>\n\n\n\n
These are ordered deliberately. Work down the list and stop as soon as you have enough space. Most of the time you never reach step four.<\/p>\n\n\n\n
1. Stopped containers<\/h3>\n\n\n\n
# See what would go\ndocker ps -a --filter status=exited --filter status=created\n\ndocker container prune<\/code><\/pre>\n\n\n\n
This removes stopped containers and their writable layers. Anything running is untouched, and named volumes attached to those containers survive \u2014 only the container’s own layer goes.<\/p>\n\n\n\n
The one caveat: if a stopped container held state in its writable layer rather than in a volume, that state is gone. That is a design problem rather than a cleanup problem, but it is worth a glance before you confirm.<\/p>\n\n\n\n
2. Build cache<\/h3>\n\n\n\n
On any machine that builds images regularly, this is usually the biggest single win and it is completely safe. Build cache is derived data. Deleting it costs you a slower next build and nothing else.<\/p>\n\n\n\n
# Everything older than a week\ndocker builder prune --filter \"until=168h\"\n\n# Everything, no exceptions\ndocker builder prune -a<\/code><\/pre>\n\n\n\n
3. Dangling images<\/h3>\n\n\n\n
# Look first\ndocker images -f dangling=true\n\ndocker image prune<\/code><\/pre>\n\n\n\n
Without -a<\/code>, this removes only dangling images \u2014 untagged layers left behind when a rebuild moved a tag to a new image. They are almost always genuine garbage.<\/p>\n\n\n\n
4. Unused images \u2014 read this one carefully<\/h3>\n\n\n\n
docker image prune -a<\/code><\/pre>\n\n\n\n
Adding -a<\/code> changes the meaning completely. It removes every image that does not have at least one container associated with it \u2014 running or<\/em> stopped. So an image you pulled for a job that runs weekly, with no container currently existing, is gone. It will pull again, which is fine if you have bandwidth and the registry is reachable, and much less fine at 3am on a machine with a slow link.<\/p>\n\n\n\n
Safer in most cases is an age filter, which keeps anything recent:<\/p>\n\n\n\n
docker image prune -a --filter \"until=336h\"   # older than 14 days<\/code><\/pre>\n\n\n\n
5. Volumes \u2014 the one that loses data<\/h3>\n\n\n\n
Volumes are where databases live. Treat this step as a data operation, not a cleanup.<\/p>\n\n\n\n
Before removing anything, look inside the candidates. This mounts each dangling volume read-only into a throwaway container so you can see what is actually in it:<\/p>\n\n\n\n
docker volume ls -qf dangling=true | while read -r v; do\n  echo \"=== $v\"\n  docker run --rm -v \"$v\":\/vol:ro alpine sh -c 'du -sh \/vol; ls -la \/vol' 2>\/dev\/null | head -12\ndone<\/code><\/pre>\n\n\n\n
If you see anything resembling a data directory, back it up before it goes:<\/p>\n\n\n\n
docker run --rm \n  -v my-volume:\/vol:ro \n  -v \"$PWD\":\/backup \n  alpine tar czf \/backup\/my-volume.tar.gz -C \/vol .<\/code><\/pre>\n\n\n\n
Only then:<\/p>\n\n\n\n
docker volume prune<\/code><\/pre>\n\n\n\n
On recent Docker versions this prunes only anonymous volumes by default, with --all<\/code> needed to include named ones \u2014 a genuinely good safety change. Older versions removed named volumes too. Check which behaviour you have before trusting it:<\/p>\n\n\n\n
docker version --format '{{.Server.Version}}'\ndocker volume prune --help<\/code><\/pre>\n\n\n\n
\n\n\n\n
The gigabytes Docker never tells you about<\/h2>\n\n\n\n
Here is the part that catches experienced people. Container logs do not appear in docker system df<\/code> at all, and no prune command touches them. A chatty application with the default logging driver will happily write tens of gigabytes and nothing in Docker’s own tooling will mention it.<\/p>\n\n\n\n
sudo du -sh \/var\/lib\/docker\/containers\/*\/*-json.log | sort -h | tail -10<\/code><\/pre>\n\n\n\n
To map a log file back to the container that owns it:<\/p>\n\n\n\n
docker ps -aq | xargs docker inspect --format '{{.Name}} {{.LogPath}}'<\/code><\/pre>\n\n\n\n
Truncate, do not delete<\/h3>\n\n\n\n
This matters. Deleting a log file that a running container still has open removes the directory entry but not the data \u2014 the kernel keeps the blocks allocated until the process closes the descriptor, so df<\/code> shows no improvement and you are left confused. Truncate instead:<\/p>\n\n\n\n
sudo truncate -s 0 \/var\/lib\/docker\/containers\/<container-id>\/<container-id>-json.log<\/code><\/pre>\n\n\n\n
Then stop it happening again<\/h3>\n\n\n\n
Set a global default in \/etc\/docker\/daemon.json<\/code>:<\/p>\n\n\n\n
{\n  \"log-driver\": \"json-file\",\n  \"log-opts\": {\n    \"max-size\": \"10m\",\n    \"max-file\": \"3\"\n  }\n}<\/code><\/pre>\n\n\n\n
sudo systemctl restart docker<\/code><\/pre>\n\n\n\n
One thing people get wrong here: this applies to newly created containers only<\/strong>. Anything already running keeps the logging config it was created with. You have to recreate those containers for the limit to take effect \u2014 restarting them is not enough.<\/p>\n\n\n\n
While you are in that file, cap the build cache too:<\/p>\n\n\n\n
{\n  \"log-driver\": \"json-file\",\n  \"log-opts\": {\n    \"max-size\": \"10m\",\n    \"max-file\": \"3\"\n  },\n  \"builder\": {\n    \"gc\": {\n      \"enabled\": true,\n      \"defaultKeepStorage\": \"20GB\"\n    }\n  }\n}<\/code><\/pre>\n\n\n\n
\n\n\n\n
Automating it without automating a disaster<\/h2>\n\n\n\n
A weekly cron is worth having, provided it only ever does the safe operations. The rule is simple: never put --volumes<\/code> in anything unattended.<\/p>\n\n\n\n
# \/etc\/cron.d\/docker-prune\n# Weekly, Sunday 03:00. Containers, networks, dangling images and build\n# cache older than seven days. No volumes, ever.\n0 3 * * 0 root \/usr\/bin\/docker system prune -f --filter \"until=168h\" >> \/var\/log\/docker-prune.log 2>&1<\/code><\/pre>\n\n\n\n
Note what docker system prune<\/code> covers without flags: stopped containers, unused networks, dangling images and build cache. It does not<\/em> touch volumes unless you explicitly pass --volumes<\/code>, and it does not remove tagged images unless you pass -a<\/code>. Those two flags are the whole difference between a routine job and an incident.<\/p>\n\n\n\n
\n
If you are tempted to add --volumes<\/code> to a cron job so you do not have to think about it again, you have swapped a disk space problem for a data loss problem on a timer.<\/p>\n<\/blockquote>\n\n\n\n
Troubleshooting<\/h2>\n\n\n\n
Pruned everything, df has not moved<\/h3>\n\n\n\n
Deleted files still held open by a running process. Find them:<\/p>\n\n\n\n
sudo lsof +L1 | head -20<\/code><\/pre>\n\n\n\n
Restarting the process that holds the descriptor releases the blocks. If it is the Docker daemon itself, a systemctl restart docker<\/code> does it, at the cost of bouncing every container without a restart policy.<\/p>\n\n\n\n
“No space left on device” but df shows free space<\/h3>\n\n\n\n
You are out of inodes rather than bytes. Docker’s layered storage creates enormous numbers of small files:<\/p>\n\n\n\n
df -i<\/code><\/pre>\n\n\n\n
The fix is the same \u2014 prune images and build cache, which is where the file count lives.<\/p>\n\n\n\n
overlay2 is huge and I have hardly any images<\/h3>\n\n\n\n
sudo du -sh \/var\/lib\/docker\/*\nsudo du -sh \/var\/lib\/docker\/overlay2 2>\/dev\/null<\/code><\/pre>\n\n\n\n
Usually build cache or container writable layers rather than images. Do not delete anything under overlay2<\/code> by hand \u2014 the directory names are referenced in Docker’s metadata, and removing them directly corrupts the daemon’s view of the world. Always go through docker<\/code> commands.<\/p>\n\n\n\n
Running low and need space right now<\/h3>\n\n\n\n
Fastest safe sequence, in order:<\/p>\n\n\n\n
docker builder prune -a -f\ndocker container prune -f\ndocker image prune -f\nsudo truncate -s 0 \/var\/lib\/docker\/containers\/*\/*-json.log<\/code><\/pre>\n\n\n\n
Four commands, no volumes touched, no tagged images removed. That resolves the large majority of Docker disk usage emergencies.<\/p>\n\n\n\n
Common mistakes<\/h2>\n\n\n\n