How to use docker image prune command to remove unused images

Introduction

In this lab, you will learn how to effectively manage disk space by removing unused Docker images using the docker image prune command. We will begin by understanding the purpose of this command and the different types of unused images it targets, specifically dangling images and all unused images.

Through hands-on exercises, you will practice removing dangling images and then extend this to remove all unused images. Furthermore, you will explore how to use filtering options with docker image prune to selectively remove images based on criteria such as creation time and labels, providing you with granular control over your image cleanup process.

Skills Graph

Understand the purpose of docker image prune

In this step, we will understand the purpose of the docker image prune command. As you work with Docker, you will inevitably accumulate unused images on your system. These images can take up significant disk space. The docker image prune command is used to remove these unused images, helping you free up disk space.

There are two main types of unused images that docker image prune targets:

1. Dangling images: These are images that are not tagged and are not referenced by any container. They are essentially intermediate layers that are no longer needed.
2. All unused images: This includes dangling images as well as images that are not referenced by any container, even if they have a tag.

Let's start by creating some dangling images to see how docker image prune works. We will pull a few different versions of the ubuntu image and then build a new image based on one of them. This process often leaves behind dangling images.

First, pull the ubuntu:latest and ubuntu:18.04 images.

docker pull ubuntu:latest
docker pull ubuntu:18.04

You should see output indicating that the images are being pulled.

Now, let's build a simple image based on ubuntu:latest. Create a file named Dockerfile in your ~/project directory with the following content:

FROM ubuntu:latest
RUN echo "Hello, Docker!" >/app/hello.txt

This Dockerfile simply starts from the ubuntu:latest image and adds a file named hello.txt to the /app directory.

Now, build the image using the docker build command. We won't tag this image, which will help create a dangling image.

docker build -t my-ubuntu-app ~/project

You should see output indicating the build process. After the build is complete, let's list all images, including intermediate ones, to see if we have any dangling images.

docker images -a

Look for images with <none> in the REPOSITORY and TAG columns. These are dangling images.

The docker image prune command is designed to remove these dangling images by default. In the next step, we will use this command to clean up the dangling images we just created.

Remove dangling images using docker image prune

In the previous step, we created some dangling images by building an image without a specific tag. In this step, we will use the docker image prune command to remove these dangling images.

By default, docker image prune only removes dangling images. This is the safest way to clean up unused image layers without accidentally removing images that you might still need, even if they are not currently associated with a running container.

To remove dangling images, simply run the docker image prune command:

docker image prune

When you run this command, Docker will show you a list of the dangling images it will remove and ask for confirmation.

WARNING! This will remove all dangling images.
Are you sure you want to continue? [y/N]

Type y and press Enter to proceed with the removal.

After the command finishes, it will report the total amount of space reclaimed.

Now, let's list all images again, including intermediate ones, to confirm that the dangling images have been removed.

docker images -a

You should no longer see images with <none> in the REPOSITORY and TAG columns that were present before running docker image prune. The ubuntu:latest, ubuntu:18.04, and my-ubuntu-app images should still be present, as they are not dangling.

This demonstrates the basic usage of docker image prune for removing dangling images. This is a good practice to perform periodically to free up disk space on your Docker host.

Remove all unused images using docker image prune -a

In the previous step, we learned how to remove dangling images using docker image prune. While removing dangling images is helpful, there might be other images on your system that are not currently used by any container but are not dangling (i.e., they have a tag). To remove these images as well, you can use the -a (or --all) flag with docker image prune.

The docker image prune -a command removes all unused images, not just dangling ones. This is a more aggressive cleanup and should be used with caution, as it will remove any image that is not currently associated with a running container.

Let's see how this works. First, let's list the images we currently have.

docker images

You should see ubuntu:latest, ubuntu:18.04, and my-ubuntu-app. These images are not currently used by any running container, but they are not dangling because they have tags.

Now, run the docker image prune -a command:

docker image prune -a

Similar to the previous step, Docker will show you a list of images it will remove and ask for confirmation.

WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N]

Type y and press Enter to proceed.

After the command finishes, it will report the total amount of space reclaimed.

Now, list the images again to see which ones remain.

docker images

You should see that all images that were not associated with a running container have been removed. If you had any running containers, the images used by those containers would not be removed.

Using docker image prune -a is a powerful way to free up a significant amount of disk space, but remember that it removes all images not currently in use.

Filter images to prune based on creation time

In addition to removing all unused images, docker image prune allows you to filter which images are considered for pruning based on various criteria. One useful filter is based on the creation time of the image. This allows you to remove images that were created before a specific point in time.

The --filter flag is used to apply filters. To filter by creation time, you use the until filter. The until filter takes a timestamp or a duration as its value. Images created after the specified time will be kept, while those created before or at the specified time will be considered for pruning.

Let's first pull a few images with different creation times. We'll pull alpine:latest and centos:latest.

docker pull alpine:latest
docker pull centos:latest

Now, let's list the images and observe their creation times.

docker images

Note the CREATED column for each image.

To demonstrate filtering by time, we need a reference point. Let's say we want to remove images created more than 5 minutes ago. We can specify the until filter with a duration like 5m.

docker image prune -a --filter "until=5m"

This command will consider removing all unused images that were created more than 5 minutes ago. Docker will again ask for confirmation before proceeding.

WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N]

Type y and press Enter to confirm.

After the pruning, list the images again:

docker images

Depending on how long ago you pulled the images and ran the prune command, some images might have been removed. Images created within the last 5 minutes should remain.

You can also specify a specific timestamp in various formats. For example, to remove images created before a specific date and time, you could use a format like "2023-10-27T10:00:00".

Filtering by creation time is useful for automating cleanup tasks, ensuring that only relatively recent images are kept on your system.

Filter images to prune based on labels

In this final step, we will explore another powerful filtering option for docker image prune: filtering based on labels. Labels are key-value pairs that you can attach to Docker objects, including images, to add metadata. You can then use these labels to filter and manage your Docker resources.

The --filter flag with the label key allows you to specify which images to include or exclude from the pruning process based on their labels.

First, let's create a couple of images with different labels. We'll use a simple Dockerfile and build two images with different labels.

Create a file named Dockerfile.labeled in your ~/project directory with the following content:

FROM alpine:latest
LABEL environment="development"
LABEL version="1.0"
RUN echo "This is a labeled image" >/app/info.txt

Now, build two images from this Dockerfile, applying different labels during the build process using the --label flag.

docker build -t my-labeled-app:dev --label project=myapp --label stage=dev ~/project -f Dockerfile.labeled
docker build -t my-labeled-app:prod --label project=myapp --label stage=prod ~/project -f Dockerfile.labeled

We have now built two images, my-labeled-app:dev and my-labeled-app:prod, both based on the same Dockerfile but with different stage labels.

Let's list the images and inspect their labels.

docker images --filter reference="my-labeled-app*" --format "{{.Repository}}:{{.Tag}} {{.Labels}}"

You should see output showing the images and their associated labels.

Now, let's use docker image prune to remove images based on their labels. Suppose we want to remove all unused images that have the label stage=dev. We can use the --filter flag with label=stage=dev. We'll also use the -a flag to consider all unused images, not just dangling ones.

docker image prune -a --filter "label=stage=dev"

Docker will show you the images that match the filter and will be removed. Confirm by typing y.

After the pruning, list the images again:

docker images --filter reference="my-labeled-app*" --format "{{.Repository}}:{{.Tag}} {{.Labels}}"

You should see that the my-labeled-app:dev image has been removed, while my-labeled-app:prod remains because it did not match the filter.

You can also use the label!=key=value syntax to remove images that do not have a specific label or label value. For example, to remove all unused images that do not have the label stage=prod:

docker image prune -a --filter "label!=stage=prod"

This command would remove my-labeled-app:dev (if it still existed) and any other unused images that don't have the stage=prod label.

Filtering by labels provides a flexible way to manage and clean up your images based on your own defined metadata.

Summary

In this lab, we learned how to use the docker image prune command to manage disk space by removing unused Docker images. We began by understanding the purpose of the command and the types of unused images it targets: dangling images (untagged and unreferenced) and all unused images (including tagged but unreferenced images). We then practiced identifying and removing dangling images using the basic docker image prune command.

We further explored the capabilities of docker image prune by learning how to remove all unused images using the -a flag. Finally, we discovered how to use filtering options to selectively prune images based on criteria such as creation time and labels, providing more granular control over image cleanup.