How to remove dangling and unused Docker images

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
how to remove dangling and unused docker images
How to remove dangling and unused Docker images
Software requirements and conventions used
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.



Comments and Discussions
Linux Forum