Docker is a free and open source OS-level virtualization system which allows us to pack and deliver applications together with their dependencies in isolated and reproducible environments called containers. Docker containers are built on the base of Images, which can become “dangling” in certain situations.
In this tutorial we learn what is a dangling image, and how to recognize and remove dangling and unused Docker images from our system.
In this tutorial you will learn:
- What are dangling and unused images
- How to recognize dangling images
- How to remove dangling and unused images

Category | Requirements, Conventions or Software Version Used |
---|---|
System | Distribution independent |
Software | Docker |
Other | Administrative privileges, knowledge of the Docker basics |
Conventions | # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command $ – requires given linux-commands to be executed as a regular non-privileged user |
What is dangling image?
Before we see how to remove dangling images, let’s clarify when an image can be identified as such; in order to do that, let’s create a new image. For the sake of this tutorial we will create and build an image based on Debian stable. In the Dockerfile definition, we just add some extra packages to the base image and we launch the bash shell as default command:
FROM debian:stable RUN apt-get update && apt-get install -y vim curl CMD ["/bin/bash"]
Supposing the Dockerfile to be in our current working directory, to build the image and tag it as
linuxconfig/debian
, we use the following command:
$ sudo docker build . -t linuxconfig/debian
The building should be completed in few seconds. Once the image is ready, we should find it included, together with the image it is based on, in the list of the existing images we can obtain by using the docker image ls
command:
$ sudo docker image ls REPOSITORY TAG IMAGE ID CREATED SIZE linuxconfig/debian latest 2703963b9db2 18 seconds ago 186MB debian stable 9b4953ae981c 2 weeks ago 124MB
As you can see the ID associated to our image is 2703963b9db2
. Now, suppose we want to modify our Dockerfile, for example to include an extra package into the image (the python3 package, in this case). We modify our Dockerfile so that it looks like in the example below:
FROM debian:stable RUN apt-get update && apt-get install -y vim curl python3 CMD ["/bin/bash"]
At this point we must re-build the image, with the same command we used before. Once the new build of the image is ready, if we check the images list, we can see a new entry for the image was created, while the previous entry was modified:
REPOSITORY TAG IMAGE ID CREATED SIZE linuxconfig/debian latest c829257789ed 4 seconds ago 215MB <none> <none> 2703963b9db2 About a minute ago 186MB debian stable 9b4953ae981c 2 weeks ago 124MB
We can easily recognize the previous entry by its ID, and we can see that
<none>
is now reported under the REPOSITORY and TAG columns. What does it mean? Since we re-built the image with the same name, the original build was untagged and its name was removed: it became a dangling image.
The ones reported in the list above, as the result of the docker image ls
command, are just the “main” images. Since Docker images are built in layers, intermediate images are created as part of the building process. Those intermediate images become themselves dangling. To make intermediate images be included in the list we must add the --all
(-a
) option to the command:
$ sudo docker image ls --all
Here is the output returned by the command, in this case:
[egdoc@fingolfin optim]$ sudo docker image ls --all REPOSITORY TAG IMAGE ID CREATED SIZE linuxconfig/debian latest c829257789ed 2 hours ago 215MB <none> <none> 3423cc3de95c 2 hours ago 215MB <none> <none> f9aa77dffe35 2 hours ago 186MB <none> <none> 2703963b9db2 2 hours ago 186MB debian stable 9b4953ae981c 2 weeks ago 124MB
Dangling images are easy to recognize in the list, as we saw above. In some cases, however, we may want to apply a filter so that only dangling images are displayed. A filter can be applied by passing it as argument to the -f
or --filter
option. In order to filter dangling images, we can use execute the following command:
$ sudo docker image ls -f dangling=true
Removing dangling images
As time passes, the number of existing dangling images can grow, so we may want to remove them in order to free some space on the filesystem. To accomplish this task we can use the docker image prune
command:
$ sudo docker image prune
Before proceeding with the actual removal, we are prompted to confirm the action:
WARNING! This will remove all dangling images. Are you sure you want to continue? [y/N]
Once we confirm, all dangling images will be removed. In certain cases we may want to avoid the confirmation prompt and make the process completely unattended (say for example we are launching the command from a scheduled script invocation); in such cases, all we have to do is to use the --force
option (-f
):
$ sudo docker image prune --force
Working with unused images
We just saw what dangling images are, and how to remove all of them with just one command; now let’s talk about unused images.
An image is considered unused when it doesn’t have any container associated to it. We can think of containers as instance of images, analogously as we consider objects as instance of classes in the Object Oriented Programming paradigm.
Removing unused images
Removing all unused images is really simple: we use the same command we used to remove dangling images, but we just add another option: --all
(-a
). This will cause all unused images (in addition to dangling ones) to be removed from the system:
$ sudo docker image prune -a WARNING! This will remove all images without at least one container associated to them. Are you sure you want to continue? [y/N]
Since in this tutorial we didn’t run any container based on our images, all of them are removed as the result of the command:
Deleted Images: untagged: linuxconfig/debian:latest deleted: sha256:c829257789ed649e0443244c540ccb4dec05a0ebacf06601235ffcba686aa50b deleted: sha256:3423cc3de95c4a025e8b7ed80e2f36ac6a1d12845ef7f06512e73b86564dd5a1 deleted: sha256:67f7591475b9165ba2f8cd745941f7f1f536c10d4dff4707c5262f81b10af43e deleted: sha256:2703963b9db2fd81f23eef2ef2e4f29d81391d827dd6e0c3c18c7cb704e9f407 deleted: sha256:f9aa77dffe35e3e55dce1d0289e44ef77c2f80ad90126559f887090bb1575e27 deleted: sha256:05ef722493a57a8835429f9ccfe33d80b6b63b4d59dfc6147c1918db898fdfb6
Conclusions
In this tutorial we learned what is a “dangling” image and when a Docker image assumes that state. We saw how to recognize dangling images, and how to filter the image list so that only dangling images are displayed. We also saw how to remove all dangling and unused images with just one command.