How to List Docker Images: A Complete Guide to Managing All Images

Docker image management begins with the process of listing Docker images to gain observability of the state of images. Listing images enables you to spot redundant images that have to be removed to boost the efficiency and performance of your machine. In this guide, you will learn how to list images, analyze, and filter the image list. In addition, you will learn how to format and filter the contents of the image list.

#Prerequisites

Ensure that you have installed Docker on your machine. If you are new to Docker and have not pulled any images yet, use the following command followed by the image name to pull any image from DockerHub:

docker pull [enter image name here]

#Why do you need to list Docker images?

The docker images command is used to output a list of images available on your local machine. This command is important because it enables you to:

Identify idle and unused Docker images; Identify duplicate images with duplicate IDs; Identify images that over-consume disk space; Fetch the image ID to check the authenticity of the image; Identify outdated images.

#How to list Docker images

There are several variations of one command that you can use to list Docker images:

1. docker images
2. docker image ls
3. docker image list

In this tutorial, we will stick to using the docker images command. Now, let's execute the command to see which images have been pulled from DockerHub:

docker images

You will get the following output that shows all images available in your machine:

REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
postgres     latest    b9390dd1ea18   3 weeks ago   431MB
nginx        latest    92b11f67642b   3 weeks ago   187MB

Below is an explanation of the image description details shown in the above output:

• Repository: The repository indicates the name of the image and its source project name. For example, an image called MySQL will have a repository called MySQL because the project that created and maintains the contents of the image is MySQL.
• Tag: Docker images are classified using their version number, the tag description states the version of the image. The tag will output the latest version if the image was pulled without a specific version number.
• Image ID: The ID serves as a unique identifier for every individual image. The image ID is created using the SHA256 hash. The hash value is determined using the configuration and layers of the image. Here is an example of an image ID: 92b11f67642b.
• Created: The “created” field states the age of the image, and how long it has been pulled.
• Size: The “size” field states the storage size of the image.

#Filtering the list of Docker images

The docker images command has many flags that you can use to filter the output and get exactly what you want. Below are examples showing you how to use different flags.

#1. The --digests flag

The --digests flag shows the full image ID hash value. The full ID value is needed to verify the integrity of the image.

docker images --digests

You will get the following output:

#2. The --quiet flag

The --quiet flag is used to give a list of image IDs only.

docker images --quiet

You will get the following output that shows image IDs only:

b9390dd1ea18
92b11f67642b

#3. The --filter flag

The --filter flag is used to get a specific image. Use the following command to get details about the nginx image only:

docker images -f "reference=nginx"

You will get the following output that only shows the nginx image:

REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
nginx        latest    92b11f67642b   4 weeks ago   187MB

#How to format the output

Below is a list of flags you can use to format the image list:

#1. Displaying images in a specific format

The --format flag enables you to print the output in different layouts. You can use this flag to get specific details such as the image name and size only without having to fill the output with the “tag” and ”created” sections.

docker images --format ": - "

The output below only shows the image name and the image size.

postgres: - 431MB
nginx: - 187MB

#2. Showing full output

To show the full details of image details without truncating the output, use the following command that uses the --no-trunc flag.

docker images --no-trunc

The output looks exactly the same as the one where you use the --digests flag. This happens because when you use the --digests flag you force Docker to give the full image ID value the same goes with the --no-trunc flag.

#3. Formatting the output to JSON

Use the following command to get the image list in JSON format.

docker images --format json

JSON output:

{"Containers":"N/A","CreatedAt":"2024-02-21 02:46:13 +0200 SAST","CreatedSince":"3 weeks ago","Digest":"\u003cnone\u003e","ID":"b9390dd1ea18","Repository":"postgres","SharedSize":"N/A","Size":"431MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"431.4MB"}

#Conclusion

In this guide, we’ve learned how to list images and filter the output using many flags. In addition, we have learned what the description fields such as repository and tag mean. Now, you are able to list Docker images to check which images are outdated and over-consuming disk space.

If you found this guide helpful, also check out how to remove Docker images, how to uninstall docker and how to create a Docker container.