docker
System Prune Docs Misleading About Named Volume Removal
Page: https://docs.docker.com/reference/cli/docker/system/prune/
Issue:
The documentation currently states:
“Prune volumes — only anonymous volumes are removed.”
However, this is inaccurate. In practice, docker system prune --volumes removes any dangling volume, whether anonymous or named, as long as it is not referenced by any container.
This behavior is clearly demonstrated in the example directly below this statement, where a named volume (named-vol) is created and later deleted via docker system prune --volumes.
Suggested correction:
“Prune volumes — only dangling volumes (volumes not currently used by any container) are removed. This includes both anonymous and named volumes.”
This change would clarify the actual behavior and prevent confusion for users relying on named volumes for persistence.
Thank you!
🙈 I'm trying to find the "only anonymous volumes are removed" wording on https://docs.docker.com/reference/cli/docker/system/prune/, and don't see it, but maybe I'm very much overlooking it 🙈
What version of docker are you running? Can you post the full output of docker version and docker info?
Trying to reproduce on a current (v28.x) version of docker;
docker volume create myvolume
myvolume
docker volume create
cfcbb1af1380f12b6b6edf9dd86005a9526aa0b51295969f990ff46657eade69
docker volume ls
DRIVER VOLUME NAME
local c699181c40cf8bcd4800870d4609f53212d4a55bba03c5c599322e38352117ec
local myvolume
docker system prune --volumes -f
Deleted Volumes:
c699181c40cf8bcd4800870d4609f53212d4a55bba03c5c599322e38352117ec
Total reclaimed space: 0B
docker volume ls
DRIVER VOLUME NAME
local myvolume
I also don't see the phrases the OP mentions, but do actually see an inconsistency. In the linked docs, it shows example:
$ docker system prune -a --volumes
<snip>
- all anonymous volumes not used by at least one container
<snip>
Deleted Volumes:
named-vol
<snip>
The message implies named volumes will be untouched, but the actual output says differently. So at some point docker must have behaved like the OP said (assuming that output was from a live example and not manufactured). Thankfully that isn't current behavior, but the example probably should be updated to reflect the current behavior and not contradict the docs.
@rrjjvv nice catch! I opened a pull request to update that example, and added you as "co-author" 😅