"docker volume prune" removes volumes that are 'referenced by a container'

So, as a beginner, I found out I had many dangling volumes.

Then I read in the documentation about docker volume prune and the documentation tells me:

Remove all unused local volumes. Unused local volumes are those which are not referenced by any containers

It turnes out that should read:

Remove all unused local volumes. Unused local volumes are those which are not referenced by any running containers

Because, when I did that while my containers were not running, docker removed all my volumes, so I lost all my persistent data. Hurray for setting op basic VM backups first in my development journey…

Of course ‘referenced by a container’ is different from ‘referenced by an image’, but again, for a beginner, this strict meaning of the word ‘container’ might not be apparent yet.

‘Dangling’ is a bit a dangerous concept here for beginners (I understand why this is so and I should have reasoned it out myself because adding volumes is a rather dynamic process that can be independent from the container image, but still: adding running to the documentation — and a warning for beginners like I am — might be a good idea)

That wouldn’t be true. If I have to guess I would say you ran your containers using Docker Compose and “stopped” the containers by running

docker compose down

or you used the --rm flag of docker run so your container was removed when you stopped it.

Volumes referenced by any running or not running container would not be removed by docker volume prune. I don’t know if it is in the documentation, but I have noticed a minute ago that volumes created as bind mounts would not be deleted either. For example:

volumes:
  test:
    driver: local
    driver_opts:
      o: bind
      type: none
      device: /mnt/test


services:
  test:
    image: httpd:2.4
    volumes:
      - type: volume
        source: test
        target: /usr/local/apache2/htdocs

It makes sense since in this case the mounted folder would not be an automatically created folder but an existing one and Docker would not delete your existing data. Even if it would delete the volume definition, your data would still be there. You don’t actually need to have data in that folder. You can use it as any volume to copy files from the container to the volume when the container starts first.

These volumes can be dangling so when you run

docker volume ls --filter dangling=true

you can see these volumes, but docker volume prune would not remove them even if you deleted and not just stopped your containers.

Thank you. Yes correct: I started/stopped them with compose up/down.

Still using ‘volume’ mounts (so data is persistent in the preferred docker way) and losing your data by a ‘prune’ action was rather unexpected for a beginner. Especially since ‘down’ has the natural language interpretation of ‘stop’ more than ‘remove’. Maybe `compose up/down’ should have been ‘compose add/delete’. Too late.

I agree. I am not a beginner and I still don’t like to use the defalt local volumes for persistent data in production, since it is too easy to acidentally remove them.

For me “down” could refer to “delete” as much as “stop”. True, not obvious. It is always reommended to read the help of each command before using since even if “down” meant “stop” it could do something that you don’t want. Once I upgraded docker and almost lost data because the upgrade changed the the storage driver. It wasn’t Docker’s fault. I didn’t know “update” meant updating/upgrading the package and not just the cache in the command “yum update” since I always used debian based systems before.

Docker is not the only software using the down and up keywords this way. My guess is that docker compose uses down because docker container rm removes containers and docker compose rm removes the containers of the specified services. docker compose delete would be more confusing since rm (remove) and delete could mean the same.

If you think the documentation should emphesize more that docker compose down deletes containers, you could open an issue on GitHub

Be careful, always read the help of the commands and I hope you will have much better experience from now on :slight_smile:

1 Like