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.