Docker disk space: 26 GB reclaimable, 0 bytes freed
My VPS reported 26.47 GB of reclaimable Docker disk space. The first cleanup command freed 0 bytes. This is the audit that found the real 22 GB, written up with the exact numbers and a script you can run.
My VPS has 290 GB of disk, and 195 GB of it was used. I ran docker system df, saw 26.47 GB of images marked reclaimable, and felt pleased with myself. Free space, one command away.
So I ran docker image prune. It printed Total reclaimed space: 0B. The box had 2 dangling images, and both were untagged builds that two of my Ghost blogs are still running from, so Docker kept every layer. Zero bytes out of a promised 26.47 GB.
I did get about 22 GB back in the end. It only happened once I stopped trusting the word "reclaimable".
What reclaimable docker disk space actually means
Here's what I started with:
$ docker system df
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images 59 22 68.74GB 26.47GB (38%)
Containers 33 18 1.247GB 147.7MB (11%)
Local Volumes 90 33 7.152GB 1.148GB (16%)
Build Cache 18 0 2.773GB 0B
$ df -h /
# 290 GB total, 195 GB used, 68%Reclaimable means space Docker estimates it could free from things it considers unused right now. It's a promise about a cleanup you haven't run yet. It doesn't tell you what any single command will actually hand back.
The catch is in how prune works. Docker's docs say docker image prune will "Remove all dangling images. If -a is specified, also remove all images not referenced by any container." Dangling means an image with no tag, usually a leftover from a rebuild. I had 2. Everything else had a tag, so plain prune walked right past it.
And -a has its own catch. It "will remove all images without at least one container associated to them", and a stopped container still counts. So does one that died weeks ago and that you've forgotten about.
The 15 containers I'd forgotten about
docker ps -a showed 15 containers that were not running. I didn't remember most of them:
- 8 anonymous
node:22-alpineone-offs from 6 weeks ago - a Selenium node container that exited 3 weeks ago
- four Asterisk lab containers, exited 4 weeks ago with exit code 255
- the container for a 17 GB voice-studio test image, dead for 7 weeks
The node ones are my own fault. I ran quick tests without --rm, the exact habit I warned about in my post on first container mistakes.
I removed 14 of them and checked again:
$ docker system df
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images 60 19 68.97GB 46.16GB (66%)
Containers 20 19 1.099GB 4.096kB (0%)
Local Volumes 92 13 7.163GB 4.417GB (61%)Read that twice. Image reclaimable went from 26.47 GB to 46.16 GB, and the disk stayed at 195 GB used. Removing those containers freed zero bytes of image space. It only moved the accounting. Images that used to belong to a dead container were now "unused", so Docker added them to the pile.
That's the whole lesson on one screen. Reclaimable gets recomputed every time references change, and it can climb while your disk doesn't move at all.
Why one image can look like three
An image is a stack of layers. Think of each layer as a bag of files. Images built on the same base share the bags they have in common, and the disk stores each bag once. docker images still shows every tag with its full stack size, as if each tag owned all its bags.
My real example: a local image, shp/speaches-local, with three tags, 0.8.2-p1, 0.8.2-p2 and 0.8.2-p3. Each reported 3.04 GB. Add them up and you'd expect 9 GB. Their unique sizes were 58.62 kB, 69.5 kB and 79.53 kB. It's one 3.04 GB base with a tiny patch on each. Deleting two of those tags frees roughly 140 kB. You don't get 6 GB.
Same story with ghcr.io/immich-app/immich-machine-learning:v3 and :v3.3.1. Both tags point at image ID 513c831cfb01. One image, reported twice at 1.11 GB.
That's why docker system df -v has SHARED SIZE and UNIQUE SIZE columns. Per Docker's docs, SHARED SIZE is the space an image shares with another one, UNIQUE SIZE is the space only that image uses, and SIZE = SHARED + UNIQUE. Unique size is the honest answer to "what do I get back if I delete this?" I ignore the SIZE column during cleanups now.
What was actually eating my disk
Sorted by unique layer cost, the heavyweights were:
- 17GB
ghcr.io/debpalash/omnivoice-studio:stable, 7 weeks old, container dead - 7.09GB
ghcr.io/gitroomhq/postiz-app:latest, running and genuinely needed - 3.56GB
ghcr.io/home-assistant/home-assistant:stable, unused, 8 days old - 3.22GB
escomputers/freepbx:17, an old tag superseded by the running:17-nofail2ban - 3.04GB the speaches image, three tags, one image
- 2.54GB
louislam/uptime-kuma:2, unused - 2.49GB
jellyfin/jellyfin:latest, unused - 2.46GB
ghcr.io/immich-app/immich-server:v3, unused - 2.22GB
selenium/node-chrome:4.26.0-20241101, 2 years old, one dead test container
Of the big ones, only Postiz was running. The 17 GB voice studio was the obvious first target.
My rule: delete only what I can re-pull. For the big one I ran docker manifest inspect first. It returned a manifest, schemaVersion 2, an OCI image index, so the tag still exists upstream and I can pull it again if a project needs it. One command turns "I hope this wasn't important" into a fact.
$ docker manifest inspect ghcr.io/debpalash/omnivoice-studio:stable
# returned a manifest: schemaVersion 2, an OCI image index
$ docker rmi ghcr.io/debpalash/omnivoice-studio:stable \
selenium/node-chrome:4.26.0-20241101 \
shp-sandbox-probe:1 \
baresip-phone:latest \
jitsi/opus-transcriber-proxy:0ad61ee \
ghcr.io/duartesantos8/opengym-api:latest \
ghcr.io/duartesantos8/opengym-web:latest \
andrius/asterisk:20 \
ghost:5-alpine \
pihole/pihole:2026.10.1 \
node:22-alpine
$ docker builder prune -f
# build cache: 2.773GB -> 880.9MB, 1.892GB reclaimedImages dropped from 68.74 GB to 45.97 GB. The build cache prune gave back another 1.892 GB (2.773 GB to 880.9 MB). On the real disk, usage went from 195 GB at 68% to 173 GB at 60%. That's about 22 GB back and 118 GB free, and I trust that number because it came from the filesystem.
If these commands hit a socket permission error, use my docker permission denied fix instead of reaching for sudo.
Deleted vs kept, and why
| Image or data | Unique size | Decision | Reason |
|---|---|---|---|
| ghcr.io/debpalash/omnivoice-studio:stable | 17GB | Deleted | Container dead for 7 weeks, tag confirmed upstream |
| selenium/node-chrome:4.26.0-20241101 | 2.22GB | Deleted | 2 years old, only a dead test container used it |
| Nine other lab and one-off tags | smaller | Deleted | Leftovers from experiments I'd finished |
| ghcr.io/gitroomhq/postiz-app:latest | 7.09GB | Kept | Running and needed |
| home-assistant, jellyfin, uptime-kuma, immich-server | about 12GB together | Kept | Still on their registries, 2-3 GB re-pull each, one experiment away from useful |
| 79 dangling volumes | 4.4GB | Kept | Volume data can't be pulled again |
Volumes are where I stopped
After the container cleanup, volume reclaimable jumped from 1.148 GB to 4.417 GB. Same trick. Nothing changed on disk.
I had 79 dangling volumes holding 4.4 GB, including named ones: postiz_postgres_data, bifrost_data, vs_test_data and shp-hf-cache. A Postgres data volume isn't something I delete because a tool calls it unused.
Images can be pulled again. Volumes can't. There's no registry for your database.
Know what docker volume prune really does, too. Docker's docs define unused local volumes as those not referenced by any container, and by default prune only removes anonymous ones. On my first run, 74 of my 79 dangling volumes were anonymous. Anonymous sounds like junk. A random hash tells you nothing about what's inside, though, and a careless prune would have taken a lot of data with it.
So I left all of them alone for now.
Docker cleanup FAQ
Why did docker image prune free nothing at all?
It only removes dangling images, and both of mine were still in use by running containers. Most of the reclaimable space sat in tagged images, which need -a, and -a skips anything a stopped container still points at.
Does deleting an image tag free disk space?
Only the unique layers behind it. If tags share layers, like my speaches tags, you get kilobytes back. Check UNIQUE SIZE in docker system df -v first.
Is docker volume prune safe to run?
Never run it blind. An image can be re-pulled. Volume data is gone once it's pruned, and anonymous volumes can still hold real data. Look inside first.
The code change: a read-only audit script
I don't want to do this by eye again, so I wrote ~/.hermes/scripts/docker_disk_audit.py. It's read-only and deletes nothing. It finds every image a container references, running or stopped, and prints the rest by unique layer cost. A second tag on the same image ID gets skipped, so Immich only shows up once.
#!/usr/bin/env python3
"""Read-only Docker disk audit. Prints what holds space, by unique layer cost."""
import re
import subprocess
def sh(*cmd):
return subprocess.run(cmd, capture_output=True, text=True, check=True).stdout
def human(b):
for unit in ("B", "kB", "MB"):
if b < 1000:
return f"{b:.0f}{unit}"
b /= 1000
return f"{b:.2f}GB"
def unique_sizes():
"""image ID -> unique bytes, taken from docker system df -v"""
out, inside = {}, False
for line in sh("docker", "system", "df", "-v").splitlines():
if line.startswith("Images space usage"):
inside = True
continue
if line.startswith("Containers space usage"):
break
cols = re.split(r"\s{2,}", line.strip())
if inside and len(cols) >= 8 and cols[0] != "REPOSITORY":
n = re.match(r"([\d.]+)([kMGT]?B)", cols[6])
out[cols[2]] = float(n.group(1)) * {"B": 1, "kB": 1e3, "MB": 1e6, "GB": 1e9,"TB": 1e12}[n.group(2)]
return out
def pinned():
"""every image ID a container still references, running or stopped"""
ids = set()
for ref in set(sh("docker", "ps", "-a", "--format", "{{.Image}}").split()):
full = subprocess.run(["docker", "image", "inspect", "-f", "{{.Id}}", ref],
capture_output=True, text=True).stdout.strip()
if full:
ids.add(full)
return ids
uniq, keep, seen = unique_sizes(), pinned(), set()
rows = []
for line in sh("docker", "images", "--format",
"{{.ID}}\t{{.Repository}}:{{.Tag}}\t{{.Size}}\t{{.CreatedSince}}").splitlines():
iid, tag, size, age = (line.split("\t") + ["", "", ""])[:4]
full = subprocess.run(["docker", "image", "inspect", "-f", "{{.Id}}", iid],
capture_output=True, text=True).stdout.strip()
key = full or iid
if key in seen: # a second tag on one image is not extra disk
continue
seen.add(key)
rows.append((uniq.get(key.split(":")[-1][:12], 0), key in keep, size, age, tag))
print(f"{'unique':>8} {'reported':>9} {'age':>14} image")
for u, used, size, age, tag in sorted(rows, reverse=True):
if not used:
print(f"{human(u):>8} {size:>9} {age:>14} {tag}")Output after the cleanup, trimmed to the parts I care about:
unique reported age image
3.55GB 3.56GB 8 days ago ghcr.io/home-assistant/home-assistant:stable
3.22GB 3.22GB 7 months ago escomputers/freepbx:17
2.46GB 2.46GB 5 weeks ago ghcr.io/immich-app/immich-server:v3
2.42GB 2.54GB 5 days ago louislam/uptime-kuma:2
2.37GB 2.49GB 3 weeks ago jellyfin/jellyfin:latest
924MB 1.11GB 5 weeks ago ghcr.io/immich-app/immich-machine-learning:v3
924MB 1.11GB 4 weeks ago ghcr.io/immich-app/immich-machine-learning:v3.3.4
88kB 13MB 12 days ago alpine:latest
80kB 3.04GB 6 weeks ago shp/speaches-local:0.8.2-p3
70kB 3.04GB 6 weeks ago shp/speaches-local:0.8.2-p2Docker says 23.5 GB reclaimable. The last two rows explain why I stopped trusting that number: two tags of a 3.04 GB image that hold 80 kB and 70 kB of their own data. A big chunk of the 23.5 GB is stuff I kept on purpose. Keeping 12 GB was a decision. It wasn't an oversight.
How this was tested: every number here comes from my own VPS on 18 Nov 2026, in one pass, with df -h and docker system df before and after.
And if you would rather have someone audit your stack, that's work I take on.
The script enforces two habits. Delete only what I can re-pull, which means docker manifest inspect before any docker rmi. And never prune volumes blind, which is why the script prints images only and leaves volume decisions to me. Reclaimable is Docker's guess. The audit plus df -h tells me what I actually got.