Inspect Docker images

This article covers four key points about verifying Docker images. To verify a Docker image, we'll use three commands as below.

docker image ls
docker image inspect
docker image history

Based on these 3 commands, I will summarize how to verify image content information, version hooks, tags, names, layers, capacity, container images, Dockerfile, etc.

1. Command to Verify the Docker Image

1.1. The ls command for general information

Let's start with the most common `ls' command for viewing docker image contents, which will give you a general idea of what's in the docker image you want.

The basic form is

$ docker image ls [OPTIONS] [REPOSITORY[:TAG]]

In general, you'll get a list of all the images currently stored in your docker environment, and the [REPOSITORY[:TAG]] part can be used to see the contents of a specific docker image.

For example, if you specify the name (repository name) and tag (version) of an image like this

docker image ls nginx:latest

You will get the following information. From the beginning, this is the image name and tag information, a unique ID, the time it was created, and the image size.

repository tag image id created size
nginx last f9c14fe76d50 4 days ago 143MB

The old Docker command docker images does the same thing, but we recommend using the newer, more organized command.

1.2. The inspect command to get more information about a specific image.

The ls command we saw in Section 1.1 returns five pieces of information: the image's name, tag, ID, creation time, and capacity. The inspect command prints all the details about a given image, including these.

The default format is

inspect docker image [OPTIONS] IMAGE [IMAGE...]

When you run the command, it outputs a lot of information in JSON format, which can take a while to scroll through. Docker provides the --format option so that you don't have to keep printing this large amount of data when you only need specific information. This option uses the Go template syntax to allow you to selectively print only the information you want.

For more information on using the `--format' option, see [Docker Container Inspection - Section 1.2] (/docker/container/inspect#1.2).

In the following sections, we'll use the ls and inspect commands and the --format option to print only the information we want.

2. Verifying the contents of a Docker image

Let's see how to check the name, version/tag, layers, and size of an image, which are frequently asked questions by Docker users.

2.1. Checking the Image Name

Docker images are objects that have not yet been instantiated as containers. As such, they don't have a name, and the repository name can be referred to as the image name. The repository name is the name of the Docker Hub repository for that image, and commercial services such as Ubuntu and Nginx are referred to as official images.

You can see the names of all the images currently stored in your Docker environment by looking at the REPOSITORY entry in the list returned by the docker image ls command.

2.2. Checking the Image Version/Tag

To check the version or tag of a docker image, you can first use the ls command. You can check the TAG entry in the image list.

Alternatively, you can check the RepoTags entry in the output of the inspect command. You can do this by issuing the following command

$ docker image inspect --format '{ {.RepoTags} }' nginx
[nginx:latest]
 
$ docker image inspect --format '{ {.RepoTags} }' mariadb:10.6
[mariadb:10.6]'

2.3. Identify image layers

Docker images consist of many layers. Each layer contains specific tasks, and different images may reuse the same layer. Therefore, how you organize your layers can make a difference in how large your Docker image is and how fast it behaves.

Docker doesn't provide specific layer information. However, you can make some guesses based on the contents of two commands: inspect and history. The actual layer contents can be determined in more detail using third-party tools.

First, you can use the inspect command to see the hash values of the layers contained in the image. In the output, look for the Layers entry in the RootFS entry. If you just want to see the hash values, you can use the following command.

$ docker image inspect --format '{ {.RootFS.Layers} }' nginx
[sha256:8cbe4b54fa88d8fc0198ea0cc3a5432aea41573e6a0ee26eca8c79f9fbfa40e3 sha256:4b8862fe7056d8a3c2c0910eb38ebb8fc08785eaa1f9f53b2043bf7ca8adbafb sha256:e60266289ce4a890aaf52b93228090998e28220aef04f128704141864992dd15 sha256:7daac92f43be84ad9675f94875c1a00357b975d6c58b11d17104e0a0e04da370 sha256:5e099cf3f3c83c449b8c062f944ac025c9bf2dd7ec255837c53430021f5a1517 sha256:4fd83434130318dede62defafcc5853d03dae8636eccfa1b9dcd385d92e3ff19]

Docker does not provide the ability to use hash values to retrieve the contents of a particular layer, for example, just to see that images share the same layer.

You can see what layers make up an image and what commands they run by using the docker image history command. These commands are based on the Dockerfile, so they are not mapped to specific layers.

The result of running the command is shown below, and you can add the --no-trunc option to get more detailed information that is not omitted.

$ docker image history nginx:latest
IMAGE          CREATED      CREATED BY                                      SIZE      COMMENT
f9c14fe76d50   5 days ago   /bin/sh -c #(nop)  CMD ["nginx" "-g" "daemon…   0B
<missing>      5 days ago   /bin/sh -c #(nop)  STOPSIGNAL SIGQUIT           0B
<missing>      5 days ago   /bin/sh -c #(nop)  EXPOSE 80                    0B
<missing>      5 days ago   /bin/sh -c #(nop)  ENTRYPOINT ["/docker-entr…   0B
<missing>      5 days ago   /bin/sh -c #(nop) COPY file:e57eef017a414ca7…   4.62kB
<missing>      5 days ago   /bin/sh -c #(nop) COPY file:36429cfeeb299f99…   3.01kB
<missing>      5 days ago   /bin/sh -c #(nop) COPY file:5c18272734349488…   2.12kB
<missing>      5 days ago   /bin/sh -c #(nop) COPY file:7b307b62e82255f0…   1.62kB
<missing>      5 days ago   /bin/sh -c set -x     && addgroup --system -…   62MB
<missing>      5 days ago   /bin/sh -c #(nop)  ENV PKG_RELEASE=1~bullseye   0B
<missing>      5 days ago   /bin/sh -c #(nop)  ENV NJS_VERSION=0.7.12       0B
<missing>      5 days ago   /bin/sh -c #(nop)  ENV NGINX_VERSION=1.25.0     0B
<missing>      6 days ago   /bin/sh -c #(nop)  LABEL maintainer=NGINX Do…   0B
<missing>      7 days ago   /bin/sh -c #(nop)  CMD ["bash"]                 0B
<missing>      7 days ago   /bin/sh -c #(nop) ADD file:88252a7f118b4d6f5…   80.5MB

For things you can't see with Docker's built-in features, it's a good idea to use a third-party tool like Dive (opens in a new tab). Dive will analyze your image and tell you what each layer contains and how to optimize it. We'll cover this in a new post, along with other tools that do similar things.

2.4. Checking the image size

The image size is nicely displayed by the ls command. You can check it with the SIZE item, or if you just want the capacity value, you can use the following command.

$ docker image ls --format '{ {.Size} }' nginx:latest
l43MB

The contents of the inspect command will give you the capacity in bytes, and you can check the Size entry.

$ docker image inspect --format '{ {.Size} }' nginx
142560184

3. Checking the images in a specific container

You can see the names of the images in a specific container with the container ls command.

$ docker container ls --all
CONTAINER ID   IMAGE          COMMAND   ...
55d8d5e95e61   mariadb:10.6   "docker-entrypoint.s…"

Alternatively, you can find more details, including environment variables, in the Config.Image section of the results of running the container inspect command.

$ docker container inspect --format '{ {.Config.Image} }' 55d8mariadb:10.6

4. Check the image's dockerfile

Docker images are created based on a Dockerfile, and images that have already been created do not store information about the Dockerfile. We can infer the contents of the Dockerfile to some extent through the history command we discussed in Section 2.'3, but there are some commands that do not exist in history, such as ADD and COPY.

So if your image is searchable on Docker Hub, you should search the contents, and if it's a custom image, you should also share the Dockerfile.

5. Conclusion

In this article, we've summarized how to check image content information based on three commands: ls, inspect, and history, and how to check tags, names, layers, capacity, container images, and Dockerfile for version hooks. I hope you find this useful when you need to check image contents.

download remove