From 00f2fd1dd5dee53919cda7ed9f5c70ba8558edb5 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 13 Feb 2015 01:17:33 +0100 Subject: [PATCH] Docs: Improve description on volume removal A comment in https://github.com/docker/docker/issues/6354#issuecomment-74160215 brought to light that the "Managing Data in containers" section contained an incorrect (or confusing) line; "Volumes persist until no containers use them" Which implies that volumes are automatically removed if they are no longer referenced by a container. This pull-request attempts to add some information explaining that volumes are never automatically removed by Docker and adds some extra hints on working with data volumes. Signed-off-by: Sebastiaan van Stijn --- docs/sources/userguide/dockervolumes.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/sources/userguide/dockervolumes.md b/docs/sources/userguide/dockervolumes.md index 4d5bd7247d..5a75f5b366 100644 --- a/docs/sources/userguide/dockervolumes.md +++ b/docs/sources/userguide/dockervolumes.md @@ -28,7 +28,12 @@ persistent or shared data: - Data volumes can be shared and reused between containers - Changes to a data volume are made directly - Changes to a data volume will not be included when you update an image -- Volumes persist until no containers use them +- Data volumes persist even if the container itself is deleted + +Data volumes are designed to persist data, independent of the container's life +cycle. Docker will therefore *never* automatically delete volumes when you remove +a container, nor will it "garbage collect" volumes that are no longer referenced +by a container. ### Adding a data volume @@ -141,6 +146,14 @@ be deleted. To delete the volume from disk, you must explicitly call `docker rm -v` against the last container with a reference to the volume. This allows you to upgrade, or effectively migrate data volumes between containers. +> **Note:** Docker will not warn you when removing a container *without* +> providing the `-v` option to delete its volumes. If you remove containers +> without using the `-v` option, you may end up with "dangling" volumes; +> volumes that are no longer referenced by a container. +> Dangling volumes are difficult to get rid of and can take up a large amount +> of disk space. We're working on improving volume management and you can check +> progress on this in [pull request #8484](https://github.com/docker/docker/pull/8484) + ## Backup, restore, or migrate data volumes Another useful function we can perform with volumes is use them for