Docker – Removing Dangling and Unused Images

polymath

1. Overview

In this tutorial, we’ll take a look at some reasons why dangling and unused images are common in We’ll then look at some ways to remove them.

It’s a good practice to clean up dangling and unused Docker images once in a while since a lot of unused images can lead to wasted disk space.

2. Unused Objects in Docker

Docker does not remove unused objects automatically. Instead, it keeps them on the disk until we explicitly ask it to remove them. Some unused objects are:

Every pulled image that does not have an active container
Every container with a stopped status
Volumes corresponding to stopped and removed containers
Build caches

Let’s explore how using Docker can lead to unnecessary images and how to remove them.

2.1. Dangling Docker Images

Dangling images are created when we overwrite them with a new image of the same name and tag.

Let’s look at a small example of how updating an image will lead to a dangling image. Below is a simple Dockerfile:

FROM ubuntu:latest
CMD ["echo", "Hello World"]

Let’s build this image:

docker build -t my-image .

We can verify that the image is created by running the below command:

docker images
REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
my-image     latest    7ed6e7202eca   32 seconds ago   72.8MB
ubuntu       latest    825d55fb6340   6 days ago       72.8MB

Suppose we add a little change to the Dockerfile:

FROM ubuntu:latest
CMD ["echo", "Hello, World!"]

Let’s rebuild the image using the same command as before and list the images again:

docker images
REPOSITORY   TAG       IMAGE ID       CREATED              SIZE
my-image     latest    da6e74196f66   4 seconds ago        72.8MB
<none>       <none>    7ed6e7202eca   About a minute ago   72.8MB
ubuntu       latest    825d55fb6340   6 days ago           72.8MB

The build created a new my-image image. As we can see, the old image is still there, but now it’s dangling. Its name and tag are set to <none>:<none>.

Please note that if we did not make a change to the Dockerfile, the image would not be rebuilt while running the build command. It will be reused from the cache.

2.2. Unused Docker Images

Unused images are images that do not have a running or stopped container associated with them.

Examples of unused images are:

Images pulled from a registry but not used in any container yet
Any image whose containers have been removed
An image tagged with an older version and not being used anymore
All dangling images

As we can see, unused images aren’t necessarily dangling. We may likely use these images in the future, and we may want to keep them. However, keeping a lot of unused images can lead to space issues.

3. Removing Unnecessary Images

We looked at a few reasons why dangling and unused images are common in Docker. Now, let’s look at a few ways to remove them.

3.1. Removing Images by ID or Name

If we know the Image ID, we can use the docker rmi command to remove the image.

docker rmi 7ed6e7202eca

This command will remove the image with the ID 7ed6e7202eca (the dangling image). Let’s recheck the images:

docker images
REPOSITORY   TAG       IMAGE ID       CREATED          SIZE
my-image     latest    da6e74196f66   18 minutes ago   72.8MB
ubuntu       latest    825d55fb6340   6 days ago       72.8MB

Alternatively, we can use the docker rmi command with the image name and tag if we want to remove a specific unused image:

docker rmi my-image:latest

3.2. Docker Image Prune

If we do not want to find dangling images and remove them one by one, we can use the docker image prune command. This command removes all dangling images.

If we also want to remove unused images, we can use the -a flag.

Let’s run the below command:

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] y

The command will return the list of image IDs that were removed and the space that was freed.

If we list the images again, we’ll find there are no images left since we did not run any container.

3.3. Docker System Prune

Finding and removing all unused objects can be tedious. To make things easier, we can use the docker system prune command.

This command, by default, will remove the below objects:

Stopped containers – containers with a stopped status
Networks that are not being used by at least one container
Dangling images
Dangling build cache – the build cache that was supporting dangling images

Additionally, we can add the -a flag to remove all unused containers, images, networks, and the entire build cache. This is useful when we want to free up a lot of space.

Let’s look at an example of this:

docker system prune -a
WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all images without at least one container associated to them
  - all build cache

Are you sure you want to continue? [y/N]

4. Conclusion

In this tutorial, we looked at why dangling and unused images are common in Docker. We also looked at ways to remove them using the rmi, image prune, and system prune commands.