Problem: what does docker system prune actually delete? container/image/volume/cache cleanup boundaries —— Trove problem library

What you will run into

Disk is tight and you want to clean Docker: docker system prune -f finishes but little space comes back; docker volume prune reports Total reclaimed space: 0B;

or the opposite — you follow a "cleanup tutorial" and images/volumes you are still using get deleted, and services fail to start.

Each prune-family command has its own default scope, and some defaults are counter-intuitive (verified: docker volume prune by default deletes only unused anonymous volumes; named volumes need -a).

Why this happens

The prune family recycles by category; every command has its own default scope, and -a/--volumes/--filter widen or narrow it:

Three defaults bite the most, all verified: ① system prune deletes stopped containers by default — you think you are clearing cache, but every docker create/exited container is gone, including ones you planned to docker start again;

② volumes are "not touched by default": system prune without --volumes deletes no volumes at all, while volume prune by default deletes only anonymous volumes (--help verbatim: -a, --all Remove all unused volumes, not just anonymous ones;

reproduced: named volume survives a plain volume prune) — two opposite defaults, mixing them up is a guaranteed trap; ③ dangling images = old images with no tag (<none>:<none>) that a newer build replaced;

image prune clears only those by default, tagged-but-unused images need -a (reproduced: prune-demo-img:latest survives system prune).

Deterministic takeaway: run docker system df before deleting; on a shared daemon, tag everything with --label and scope cleanups with --filter label=...; never run an unfiltered system prune -a on shared state.

Step by step

1. See where the space went — Must do

docker system df
# Images / Containers / Local Volumes / Build Cache — look before you delete

2. Containers — By diagnosis

Stopped containers: docker container prune -f; to scope precisely: docker container prune -f --filter label=my-project=true (reproduced: only matching containers removed).

3. Images — By diagnosis

docker image prune -f clears dangling only; -a also removes unused tagged images (reproduced: default system prune removed the dangling image but kept prune-demo-img:latest; docker image rm <tag> removes tagged ones).

No unfiltered -a on shared state.

4. Volumes — Must do (easiest to delete or to miss)

docker volume ls -f dangling=true      # unused volume list; confirm manually first
docker volume prune -a -f              # default only deletes anonymous! -a includes named

Reproduced: docker volume prune -f deleted only the anonymous volume; prune-demo-named survived; docker volume prune -a -f --filter label=prune-demo=true deleted it.

5. Build cache — Optional

docker builder prune -f: only slows the next build; does not affect images/containers.

How to confirm the cleanup was safe

After pruning, docker ps -a, docker images, docker volume ls still show everything you need; docker compose up starts fine (volume data and tagged images are still there).

Reproduced: default system prune kept the tagged image and the named volume; only stopped containers/dangling images/unused networks went away.

Other environments

Symptom

# Cleanup did not free space (volumes untouched)
$ docker volume prune -f
Total reclaimed space: 0B        # named volumes are not in the default scope — that is why

# Cleanup tutorial backfired: images in use were deleted
$ docker system prune -a -f      # all unused tagged images gone -> next start re-pulls

Signature: space unchanged after prune (volumes/tagged images not covered by defaults); or blowback (unfiltered -a deleted shared images).

Cause

Prune-family commands have different default scopes: system prune includes stopped containers and dangling images but no volumes; volume prune deletes only unused anonymous volumes by default; tagged-but-unused images need -a. Unfiltered -a/--volumes on a shared daemon deletes things other people need.

Solution

1. docker system df to see the four categories first;
2. Pick the command by target: containers=container prune, dangling images=image prune, volumes=volume prune -a (after confirming), cache=builder prune;
3. On shared environments, label everything and scope cleanups with --filter label=;
4. Re-check with docker ps -a / docker images / docker volume ls after deleting.

Related canonicals

Read in order: precondition -> same root / same domain / related:

• Related (similar errors, different cause):
• WSL reports No space left but df has space (same "out of space" family: WSL vhdx vs Docker usage)
• docker compose stack fails to start: dependency not ready (same-batch Docker domain reproduction)