Dangling Docker images are untagged and unused layers that exist on your host’s filesystem. You might not be aware of their presence and they’re usually unwanted garbage.
In this article you’ll learn how dangling images arise and what you can do to clean them up. It’s a good idea to periodically inspect how many dangling images you have so you can avoid wasting your disk’s capacity.
What Is a Dangling Image?
A dangling image is simply an unused image that’s got no name and tag. You can easily spot dangling images when you run the docker images command because they show up as <none>:<none>.
In this example, the first image in the list is a dangling image:
$ docker images <none> <none> 509bc96b727d 2 months ago 55.3MB mysql 5.7 f26e21ddd20d 4 months ago 450MB gcr.io/k8s-minikube/kicbase v0.0.30 1312ccd2422d 6 months ago 1.14GB hello-world latest feb5d9fea6a5 11 months ago 13.3kB
The image is untagged but still lingering on your system. In this case 55.3 MB of disk space is being consumed.
You can verify the image is dangling and not just unused by checking whether any container references it:
$ docker ps -a CONTAINER ID IMAGE COMMAND CREATED STATUS 2aa683500ee0 gcr.io/k8s-minikube/kicbase:v0.0.30 "/usr/local/bin/entr..." 18 hours ago Exited (130) 18 hours ago
No container references the <none>:<none> image with ID 509bc96b727d so it’s definitely dangling. Note that the MySQL and Hello World images don’t class as dangling – despite being unused by containers, they’re properly tagged so it’s assumed you’ll want to keep them.
How Are Dangling Images Created?
Dangling images are usually created when an existing image gets superseded by a new build. Here’s a simple Dockerfile to demonstrate what happens:
FROM alpine:latest COPY demo.txt /demo.txt
Create a file called demo.txt in your working directory and add some content to it:
$ echo 1 > demo.txt
Now build your image with docker build:
$ docker build -t demo:latest .
Run the docker images command to see your new image:
REPOSITORY TAG IMAGE ID CREATED SIZE demo latest 40395b6c1362 24 seconds ago 5.54MB
Now modify the contents of demo.txt and rebuild your image:
$ echo 2 > demo.txt $ docker build -t demo:latest .
The same image tag is used – demo:latest – so this build supersedes the first one. Run docker images to see the effect:
REPOSITORY TAG IMAGE ID CREATED SIZE demo latest 3d5052e52b4c 3 seconds ago 5.54MB <none> <none> 40395b6c1362 59 seconds ago 5.54MB
The new image has been created with ID 3d5052e52b4c and the demo:latest tag. The first image, ID 40395b6c1362, still exists but has been untagged. It now shows as <none>:<none>. This image has become a dangling image as no containers use it.
Can You Use a Dangling Image?
Dangling images function like any other image. The only difference is the missing tag. You can start a container from a dangling image by directly referencing the image’s ID:
$ docker run -it 40395b6c1362 sh / #
Technically, the image is no longer dangling, because it’s now actively used by a container. It’s common for containers to end up with a none image if you remove or rebuild the tag they used. Containers with an untagged image will show the image’s ID in the IMAGE column when you run docker ps, instead of the usual tag.
$ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 26d5609ba75c 40395b6c1362 "sh" 2 seconds ago Up 1 second inspiring_lederberg 91ab866b59a2 portainer/portainer-ce "/portainer" 2 weeks ago Up 2 days 8000/tcp, 9443/tcp portainer_portainer_1
Cleaning Up Dangling Images
You can delete a single dangling image using the docker rmi command, just like any other image. Because the image won’t be tagged, you’ll need to identify it by its ID.
$ docker rmi 40395b6c1362
A better way to clean up many dangling images is the docker image prune command. This will automatically remove all the dangling images on your Docker host.
$ docker image prune Total reclaimed space: 5.54 MB
The command’s output shows the amount of disk space that was freed. Check whether your images are actually dangling if nothing gets deleted. It’s not possible to remove images actively used by containers. You’ll need to delete the containers with docker rm first, before you try to prune your images.
You could find you’ve got a dangling image that you actually want to reuse in the future. In this situation you can re-tag it with the docker tag command. This will make the image easier to identify and prevent it being targeted by future pruning operations.
$ docker tag 40395b6c1362 demo:latest
Images that display as <none>:<none> might not be dangling images. Confusingly, this situation also occurs for images created as the intermediate layers during a build.
Each step in a Dockerfile results in a new intermediate layer being created. The image produced at the end of the build gets assigned the tag you specify. The other intermediate layers remain untagged and can be viewed by running docker images -a.
These layers are not dangling images because the later images in the build chain depend upon them. They’re referenced by each successive layer and don’t cause a disk space problem. You can stop intermediate layers being persisted to disk by including the --rm flag at build time:
$ docker build --rm -t demo:latest .
Summary
Dangling images are untagged Docker images that aren’t used by a container or depended on by a descendant. They usually serve no purpose but still consume disk space. You’ll accumulate dangling images when you replace an existing tag by starting a new build.
All dangling images show as <none>:<none> in the Docker CLI. Having too many of them can be overwhelming when you’ve got dozens of images with no information about their true identity. Regularly running docker images prune will avoid disk space wastage and result in a shorter image list.
