How to use docker image ls command to list and filter images

Introduction

In this lab, you will learn how to effectively use the docker images command to list and filter Docker images on your system. You will begin by listing all top-level images, then explore how to list images by specific name and tag.

Furthermore, you will delve into filtering images based on their dangling status and by applying labels. Finally, you will learn how to customize the output format of the docker images command using a custom template for more tailored information display.

Skills Graph

List all top-level images

In this step, you will learn how to list all top-level Docker images on your system. Top-level images are the images that you explicitly pull or build. They are not intermediate images created during the build process.

To list all top-level images, you can use the docker images command. This command will display a table with information about each image, including the repository, tag, image ID, creation time, and size.

Let's try listing the images. Since this is a fresh environment, there might not be many images initially. We will pull an image in a later step.

Open your terminal in the ~/project directory and run the following command:

docker images

You should see output similar to this (the exact output may vary depending on the images present):

REPOSITORY    TAG       IMAGE ID       CREATED       SIZE

This output indicates that there are currently no top-level images on your system.

List images by name and tag

In this step, you will learn how to list specific Docker images by their name and tag. This is useful when you have many images and want to find a particular one.

The docker images command allows you to specify a repository name and optionally a tag to filter the output. The format is docker images [REPOSITORY[:TAG]].

First, let's pull an image so we have something to list. We will pull the hello-world image, which is a very small image used for testing.

Run the following command to pull the hello-world image:

docker pull hello-world

You should see output indicating that the image is being pulled and downloaded:

Using default tag: latest
latest: Pulling from library/hello-world
...
Status: Downloaded newer image for hello-world:latest
docker.io/library/hello-world:latest

Now that we have the hello-world image, let's list only this image using its name.

Run the following command:

docker images hello-world

The output should show only the hello-world image:

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
hello-world   latest    <image_id>     <created_time>   <size>

You can also specify a tag. Since we pulled the latest tag, let's list the hello-world image with the latest tag.

Run the following command:

docker images hello-world:latest

The output will be the same as the previous command, as latest is the default tag if none is specified:

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
hello-world   latest    <image_id>     <created_time>   <size>

If you try to list an image that doesn't exist, you will get an empty output. For example:

docker images non-existent-image

Output:

REPOSITORY    TAG       IMAGE ID       CREATED       SIZE

This confirms that you can filter images by their name and tag.

Filter images by dangling status

In this step, you will learn how to filter Docker images based on their "dangling" status. Dangling images are layers that have no relationship to any tagged images. They are often the result of building new versions of an image, which leaves the old layers without a tag. These dangling images consume disk space and can be cleaned up.

To filter images by their dangling status, you can use the --filter flag with the dangling key. The value can be true to show only dangling images or false to show only non-dangling images.

First, let's create a dangling image. We can do this by building a new image that replaces an existing one. We'll use a simple Dockerfile for this.

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

FROM alpine
CMD ["echo", "Hello, world!"]

This Dockerfile is very simple. It uses the alpine image as a base and just prints "Hello, world!" when a container is run from it.

Now, let's build an image from this Dockerfile and tag it.

Run the following command to build the image and tag it as my-image:latest:

docker build -t my-image:latest .

You should see output indicating the build process:

[+] Building
...
Successfully built <image_id>
Successfully tagged my-image:latest

Now, let's modify the Dockerfile slightly and build it again with the same tag. This will create a new image with the my-image:latest tag, and the previous image that had this tag will become dangling.

Edit the Dockerfile in your ~/project directory to change the command:

FROM alpine
CMD ["echo", "Hello again!"]

Now, build the image again with the same tag:

docker build -t my-image:latest .

You will see output similar to the previous build, but a new image ID will be generated. The previous image with the my-image:latest tag is now dangling.

Let's list all images to see the dangling image.

Run the command:

docker images

You might see an image with <none> in the REPOSITORY and TAG columns. This is a dangling image.

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
my-image      latest    <new_image_id> <created_time>   <size>
<none>        <none>    <old_image_id> <created_time>   <size>
hello-world   latest    <image_id>     <created_time>   <size>

Now, let's filter to show only the dangling images using the --filter dangling=true flag.

Run the command:

docker images --filter dangling=true

You should see only the dangling image:

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
<none>        <none>    <old_image_id> <created_time>   <size>

To see only non-dangling images, you can use --filter dangling=false.

Run the command:

docker images --filter dangling=false

This will list all images that are not dangling:

REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
my-image      latest    <new_image_id> <created_time>   <size>
hello-world   latest    <image_id>     <created_time>   <size>

This demonstrates how to filter images based on their dangling status.

Filter images by label

In this step, you will learn how to filter Docker images based on labels. Labels are key-value pairs that you can attach to Docker objects, including images. They are useful for organizing and identifying images.

To filter images by label, you use the --filter flag with the label key. The value can be a single label (label=<key>=<value>) or just the label key (label=<key>) to find images with that label regardless of its value.

First, let's create a new Dockerfile that includes labels.

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

FROM alpine
LABEL maintainer="LabEx User"
LABEL version="1.0"
CMD ["echo", "Image with labels!"]

This Dockerfile is similar to the previous one but includes two LABEL instructions.

Now, let's build an image from this Dockerfile and tag it.

Run the following command to build the image and tag it as labeled-image:latest:

docker build -t labeled-image:latest -f Dockerfile.labeled .

You should see output indicating the build process and the successful tagging of the image.

Now, let's list all images to see the newly created image.

Run the command:

docker images

You should see labeled-image in the list along with the other images.

REPOSITORY      TAG       IMAGE ID       CREATED        SIZE
labeled-image   latest    <image_id>     <created_time>   <size>
my-image        latest    <new_image_id> <created_time>   <size>
<none>          <none>    <old_image_id> <created_time>   <size>
hello-world     latest    <image_id>     <created_time>   <size>

Now, let's filter images by the maintainer label. We'll filter for images where the maintainer label has the value "LabEx User".

Run the command:

docker images --filter label=maintainer=LabEx User

You should see only the labeled-image:

REPOSITORY      TAG       IMAGE ID       CREATED        SIZE
labeled-image   latest    <image_id>     <created_time>   <size>

You can also filter by just the label key, regardless of the value. Let's filter for images that have the version label.

Run the command:

docker images --filter label=version

You should again see only the labeled-image:

REPOSITORY      TAG       IMAGE ID       CREATED        SIZE
labeled-image   latest    <image_id>     <created_time>   <size>

This demonstrates how to filter images using labels.

Format the output using a custom template

In this step, you will learn how to format the output of the docker images command using a custom template. This is useful when you want to extract specific information about images in a machine-readable format or a custom human-readable format.

The docker images command supports the --format flag, which allows you to specify a Go template to control the output. You can use various placeholders within the template to access different attributes of the image.

Let's try formatting the output to show only the image ID and repository name, separated by a colon.

Run the following command:

docker images --format "{{.ID}}: {{.Repository}}"

You should see output similar to this, listing the image ID and repository for each image:

<image_id>: hello-world
<new_image_id>: my-image
<old_image_id>: <none>
<image_id>: labeled-image

Notice that the dangling image still shows <none> for the repository.

You can also include other attributes like the tag and size. Let's format the output to show the repository, tag, and size, separated by tabs.

Run the following command:

docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

Using table at the beginning of the format string creates a table-like output with headers.

You should see output similar to this:

REPOSITORY          TAG                 SIZE
hello-world         latest              <size>
my-image            latest              <size>
<none>              <none>              <size>
labeled-image       latest              <size>

You can find a list of available placeholders in the Docker documentation for the docker images command. Some common ones include:

• .ID: Image ID
• .Repository: Image repository name
• .Tag: Image tag
• .Created: Time when the image was created
• .Size: Image size
• .Containers: Number of containers using the image

Experiment with different templates to see how you can customize the output. For example, to list the image ID and creation time:

docker images --format "{{.ID}} created at {{.Created}}"

This step concludes the lab on listing and filtering Docker images. You have learned how to list all images, filter by name, tag, dangling status, and labels, and format the output using custom templates.

Summary

In this lab, you learned how to use the docker images command to list and filter Docker images. You started by listing all top-level images on your system. Then, you practiced listing specific images by their name and tag after pulling the hello-world image.

You also explored how to filter images based on their dangling status and by specific labels. Finally, you learned how to customize the output format of the docker images command using a custom template, allowing you to display only the information you need.