How to use docker image rm command to remove images

Introduction

In this lab, you will learn how to effectively manage Docker images by using the docker image rm command. We will begin by listing the existing images on your system to understand what you have.

Following that, we will explore different scenarios for removing images, including attempting to remove an image with multiple tags, removing an image by its tag, removing an image by its ID using the force option, and finally, removing an image by its digest. This hands-on experience will equip you with the necessary skills to clean up unused or unwanted Docker images.

Skills Graph

List existing images

In this step, we will learn how to list the Docker images that are currently available on your system. Docker images are the building blocks of containers. They are read-only templates used to create containers.

To list the images, you can use the docker images command. This command shows you a list of all images that Docker has downloaded or built on your machine.

Let's try it. Open your terminal and run the following command:

docker images

You should see output similar to this (the exact images and details may vary depending on what you have previously done with Docker):

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
ubuntu        latest    270000000000   2 weeks ago    77.8MB
hello-world   latest    d00000000000   2 months ago   13.3kB

The output provides several pieces of information about each image:

• REPOSITORY: The name of the image.
• TAG: A specific version of the image. latest is the default tag if none is specified.
• IMAGE ID: The unique identifier for the image.
• CREATED: How long ago the image was created.
• SIZE: The size of the image.

Understanding the images you have is the first step in managing them. In the next steps, we will explore how to remove images.

Attempt to remove an image with multiple tags

In this step, we will explore what happens when you try to remove a Docker image that has multiple tags pointing to the same image ID. This is a common scenario when you tag an image with different versions or names.

First, let's pull an image and tag it with an additional tag. We will use the hello-world image for this example. If you already have it, the pull will be very fast.

docker pull hello-world

Now, let's add another tag to this image using the docker tag command. The syntax is docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]. We will tag the hello-world:latest image with a new tag called hello-world:mytag.

docker tag hello-world:latest hello-world:mytag

Now, let's list the images again to see the new tag.

docker images

You should see two entries for hello-world, one with the latest tag and one with the mytag tag, but both will have the same IMAGE ID.

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
ubuntu        latest    270000000000   2 weeks ago    77.8MB
hello-world   latest    d00000000000   2 months ago   13.3kB
hello-world   mytag     d00000000000   2 months ago   13.3kB

Now, let's try to remove the image using one of the tags, for example, hello-world:latest, using the docker rmi command.

docker rmi hello-world:latest

You will notice that Docker doesn't actually remove the image data itself. Instead, it removes the specific tag you specified. The output will indicate that it is "Untagged".

Untagged: hello-world:latest

If you list the images again, you will see that the hello-world:latest entry is gone, but the hello-world:mytag entry (with the same IMAGE ID) still exists.

docker images

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
ubuntu        latest    270000000000   2 weeks ago    77.8MB
hello-world   mytag     d00000000000   2 months ago   13.3kB

This demonstrates that when an image has multiple tags, removing a single tag only removes that specific reference to the image data. The image data itself is only removed when the last tag pointing to it is removed, or when you explicitly remove it by its ID (which we will cover later).

Remove an image by tag

In the previous step, we saw that removing a tag only untags the image if other tags or containers are still referencing it. In this step, we will remove the last remaining tag for the hello-world image, which should result in the image data being removed.

We currently have the hello-world image with the mytag tag. Let's confirm this by listing the images:

docker images

You should see the hello-world:mytag entry.

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
ubuntu        latest    270000000000   2 weeks ago    77.8MB
hello-world   mytag     d00000000000   2 months ago   13.3kB

Now, let's remove the hello-world image using the mytag tag with the docker rmi command:

docker rmi hello-world:mytag

This time, since mytag was the only tag referencing this image ID, Docker will remove both the tag and the underlying image data. The output will show that it's "Untagged" and then "Deleted".

Untagged: hello-world:mytag
Deleted: sha256:d000000000000000000000000000000000000000000000000000000000000000
Deleted: sha256:0000000000000000000000000000000000000000000000000000000000000000
... (more Deleted lines)

Let's list the images again to confirm that the hello-world image is gone:

docker images

The hello-world image should no longer appear in the list.

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
ubuntu        latest    270000000000   2 weeks ago    77.8MB

This demonstrates the standard way to remove an image when it's not being used by any containers and only has one tag.

Remove an image by ID using force

In this step, we will learn how to remove a Docker image using its Image ID, and specifically, how to use the force option (-f or --force) when necessary. Removing by ID is useful when you want to be precise about which image you are removing, especially if multiple tags point to the same image.

First, let's pull an image that we can then remove by ID. We'll use the ubuntu image. If you already have it, the pull will be quick.

docker pull ubuntu

Now, list the images to get the Image ID of the ubuntu image.

docker images

Find the ubuntu image in the output and note its IMAGE ID. It will be a long string of hexadecimal characters. You only need the first few characters (usually 3 or more) to uniquely identify the image.

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
ubuntu        latest    270000000000   2 weeks ago    77.8MB

Let's try to remove the image using its ID without the force option first. Replace YOUR_IMAGE_ID with the actual Image ID you noted from the docker images output.

docker rmi YOUR_IMAGE_ID

If the image is not being used by any running or stopped containers, this command will likely succeed and remove the image. However, if there is a container based on this image, you will get an error message indicating that the image is being used by a container and cannot be removed.

To demonstrate the use of the force option, let's first run a container based on the ubuntu image.

docker run -d ubuntu sleep 3600

This command runs an Ubuntu container in detached mode (-d) and keeps it running for an hour (sleep 3600).

Now, try to remove the ubuntu image by its ID again without the force option.

docker rmi YOUR_IMAGE_ID

You should receive an error message similar to this:

Error response from daemon: conflict: unable to remove repository reference "ubuntu:latest" (must force) - image is referenced by one or more containers: 000000000000 (created ...)

This error occurs because a container is using the image. To remove an image that is being used by a container, you need to use the force option (-f).

Now, let's remove the image using its ID with the force option. Replace YOUR_IMAGE_ID with the actual Image ID.

docker rmi -f YOUR_IMAGE_ID

The force option tells Docker to remove the image even if it is being used by a container. Docker will first stop and remove any containers that are using the image, and then remove the image itself. The output will show that the image and its layers are deleted.

Untagged: ubuntu:latest
Deleted: sha256:2700000000000000000000000000000000000000000000000000000000000000
Deleted: sha256:0000000000000000000000000000000000000000000000000000000000000000
... (more Deleted lines)

List the images again to confirm that the ubuntu image is gone.

docker images

The ubuntu image should no longer be in the list.

Using the force option should be done with caution, as it will stop and remove containers without further confirmation.

Remove an image by digest

In this final step, we will learn how to remove a Docker image using its digest. An image digest is a cryptographically secure identifier for the image's content. It uniquely identifies the exact layers and configuration of an image, regardless of its tags.

First, let's pull an image that we can remove by digest. We'll use the alpine image for this example.

docker pull alpine

Now, to see the digest of the image, you can use the docker images --digests command.

docker images --digests

Look for the alpine image in the output. You will see a DIGEST column with a value that starts with sha256:. This is the image digest.

REPOSITORY    TAG       DIGEST                                                                    IMAGE ID       CREATED        SIZE
ubuntu        latest    <none>                                                                    270000000000   2 weeks ago    77.8MB
alpine        latest    sha256:0000000000000000000000000000000000000000000000000000000000000000   000000000000   3 weeks ago    5.59MB

To remove the image by its digest, you use the docker rmi command followed by the image name and the digest in the format REPOSITORY@DIGEST. Replace YOUR_ALPINE_DIGEST with the actual digest you found in the previous output.

docker rmi alpine@YOUR_ALPINE_DIGEST

The output will show that the image is deleted.

Deleted: sha256:0000000000000000000000000000000000000000000000000000000000000000
Deleted: sha256:0000000000000000000000000000000000000000000000000000000000000000
... (more Deleted lines)

List the images again to confirm that the alpine image is gone.

docker images

The alpine image should no longer be in the list.

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
ubuntu        latest    <none>                                                                    270000000000   2 weeks ago    77.8MB

Removing by digest is the most specific way to remove an image, ensuring you remove the exact version of the image identified by that digest.

Summary

In this lab, we learned how to manage Docker images using the docker images and docker rmi commands. We started by listing existing images to understand their repository, tag, ID, creation time, and size.

We then explored the process of removing images. We attempted to remove an image with multiple tags, observing that docker rmi removes only the specified tag, not the underlying image ID, if other tags still reference it. We successfully removed an image by specifying its tag and also demonstrated how to remove an image by its ID, including the use of the force flag (-f) when necessary. Finally, we learned how to remove an image using its digest, which provides a unique and immutable identifier for the image content.