This blog post provides an initial overview of docker commands you can use for the administration of your Docker system.
Such administration tasks include listing and deleting images, containers, and volumes.
Determining Space Requirements of Images and Containers
How much space is actually required for images or for the container layer (i.e., for the data of a container that deviates from the original image)? This question is answered by the docker images and docker ps -a -s commands.
docker images returns a list of all downloaded or custom images, including size information:
REPOSITORY TAG ... CREATED SIZE SIZE
wordpress latest 17 hours ago 550MB
mariadb latest 7 days ago 405MB
phpmyadmin/phpmyadmin latest 2 months ago 477MB
By default, docker ps lists only the running containers. The -a option extends the output to all containers that have ever been set up. -s adds the SIZE column. It indicates how much space those files take up that have been changed in comparison to the image. Provided that most of the mutable data is stored in a volume, the additional space required is often tiny. However, when there are changes, the actual space required in the local file system is often noticeably larger than docker ps suggests. This is due to the overhead of the file system when many small files are stored.
The information in parentheses (virtual) refers to the total size of the container, including the read-only images. This data is virtual in that multiple containers can share common images, as it were.
docker ps -a -s
CONTAINER ID IMAGE ... SIZE
2bf9e954b4b7 wordpress 20.1MB (virtual 571MB)
3af937080228 phpmyadmin/... 70B (virtual 477MB)
ac98aca37f7a mariadb 2B (virtual 405MB)
Deleting Containers and Images
docker rm <id> or docker rm <name> deletes the specified container. If necessary, you can determine container IDs and names with docker ps -a.
docker rm ac98aca37f7a
Caution: docker rm has a lot of similarities with the classic rm command on Linux: it deletes without confirmation and without the option to undo the operation!
The following command first uses ps to generate a list of all IDs of containers derived from the image, ubuntu. This list is then passed to docker rm to delete all containers. So, if you’ve experimented with docker run ubuntu for a while, you can delete all the created containers on this occasion. Note that this command works only on macOS and Linux, not on Windows. The concatenation of two commands presented here assumes that a shell such as bash or zsh is used, as is the case by default on Linux or macOS. On Windows, the command works as well, as long as you use PowerShell.
docker rm $(docker ps -a -q -f ancestor=ubuntu)
The next command is even more radical as it deletes all existing containers!
docker rm $(docker ps -aq)
docker rmi imagename deletes the specified image. This is possible only if there are no containers derived from the image. The following commands first delete all helloworld containers and then the hello-world image:
docker rm $(docker ps -a -q -f ancestor=hello-world)
docker rmi hello-world
Volumes are stored separately from containers and images in their own directory, for example, in /var/lib/docker/volumes on Linux. When you delete containers, Docker generally doesn’t touch any volumes. However, you can determine a list with the names or IDs of all volumes for which the associated container no longer exists, as follows:
docker volume ls -q -f dangling=true
The size of the volumes can be determined by passing the preceding result to du. However, this only works in this way on a Linux host. On Windows and macOS, Docker files are stored in a separate file system inside a virtual machine, which you can’t access directly from the outside.
du -h --max 0 \
/var/lib/docker/volumes/$(docker volume ls -q -f dangling=true)
You can delete all orphaned volumes with the following command if necessary. The query that would pop up can be suppressed using -f.
docker volume prune
WARNING! This will remove all volumes not used by at least
one container. Are you sure you want to continue? [y/N] y
A compact overview of the space requirements of all images, containers, volumes, and the build cache is provided by docker system df:
docker system df
TYPE TOTAL ACTIVE SIZE RECLAIMABLE
Images 18 11 10.72GB 1.854GB (17%)
Containers 33 4 496MB 495.9MB (99%)
Local Volumes 2 1 169MB 119.8MB (70%)
Build Cache 0 0 0B 0B
If you also pass the -v option, the command will list all images, containers, volumes, and so on.
Releasing Unused Space
Instead of searching for images, containers, and volumes and deleting them one by one, you can use docker system prune to help you with your cleanup tasks. This command deletes all containers that aren’t currently running and all images that aren’t needed by other images (dangling images).
The large-scale cleanup becomes even more intensive with additional options:
- -a or --all also deletes images that aren’t used by containers.
- --volumes also deletes volumes that aren’t associated with any container. (Caution: Data in non-associated volumes will be lost and cannot be reused in another container!)
docker system prune -a --volumes
WARNING! This will remove:
- all stopped containers
- all networks not used by at least one container
- all volumes not used by at least one container
- all images without at least one container associated to them
- all build cache
Are you sure you want to continue? [y/N]
Editor’s note: This post has been adapted from a section of the book Docker: Practical Guide for Developers and DevOps Teams by Bernd Öggl and Michael Kofler.