See the official reference for docker system prune
docker system prune
will remove:
- all stopped containers
- all networks not used by at least one container
- all dangling images
- all build cache
docker system prune -a
will do the same, but in additional to removing all dangling images, it will more broadly remove:
- all images without at least one container associated to them
What are dangling images?
Docker images consist of multiple layers that get wrapped inside a parent 'container layer' when the overall container image is generated from a Dockerfile. Dangling images are layers that have no relationship to any other tagged images, and will therefore never have any use within any new containers that are built. They no longer serve a purpose and consume disk space.
For example a dangling image can be created by the following process:
Build a named image my-image
from Dockerfile, without specifying any tag:
FROM ubuntu:latest
CMD ["echo", "Hello World"]
docker build -t my-image
docker images
REPOSITORY TAG IMAGE ID
my-image latest 7ed6e7202eca <--- created, not dangling
ubuntu latest 825d55fb6340
Update the Dockerfile:
FROM ubuntu:latest
CMD ["echo", "Hello, World!"]
Rebuild image re-using the previous name, without specifying any tag:
docker build -t my-image
docker images
REPOSITORY TAG IMAGE ID
my-image latest da6e74196f66 <--- replacement layer
<none> <none> 7ed6e7202eca <--- previous layer, now dangling
ubuntu latest 825d55fb6340
The build created a new my-image
layer. As we can see, the layer that was originally created is still there, but its name and tag are set to <none>:<none>
. It will never be possible for this layer to be associated with any docker container layer, which means it's 'dangling'
What are images without at least one container associated to them?
An unused image means that it has not been assigned or used in a container. For example, docker ps -a
will list all of your running and stopped containers. Any image being used by any of these containers is a "used image".
When running docker system prune -a, it will remove both unused and dangling images. Any image with at least one container associated to it will not be affected.