Dangling docker images are images that are not currently being used by the docker daemon. This can be caused by a number of reasons, such as a broken image or an image that is outdated. If you see an image that is dangling, please report it to the docker daemon so that we can fix it.

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 :.

In this example, the first image in the list is a dangling image:

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:

No container references the : 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:

Create a file called demo.txt in your working directory and add some content to it:

Now build your image with docker build:

Run the docker images command to see your new image:

Now modify the contents of demo.txt and rebuild your image:

The same image tag is used – demo:latest – so this build supersedes the first one. Run docker images to see the effect:

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 :. 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:

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.

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.

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.

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.

What About Intermediate Layers?

Images that display as : 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:

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 : 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.