How to use docker image history command to inspect image layers

Introduction

In this lab, you will learn how to use the docker history command to inspect the layers of a Docker image. Understanding image layers and their creation commands is crucial for debugging and optimizing your Docker images.

You will begin by viewing the basic history of an image, then explore options to disable output truncation for full command visibility, and use the quiet output mode for a concise view. Furthermore, you will learn how to format the history output using Go templates for customized reporting and how to show history for images built for specific platforms.

Skills Graph

%%%%{init: {'theme':'neutral'}}%%%% flowchart RL docker(("Docker")) -.-> docker/ContainerOperationsGroup(["Container Operations"]) docker(("Docker")) -.-> docker/ImageOperationsGroup(["Image Operations"]) docker/ContainerOperationsGroup -.-> docker/inspect("Inspect Container") docker/ImageOperationsGroup -.-> docker/pull("Pull Image from Repository") docker/ImageOperationsGroup -.-> docker/images("List Images") subgraph Lab Skills docker/inspect -.-> lab-555153{{"How to use docker image history command to inspect image layers"}} docker/pull -.-> lab-555153{{"How to use docker image history command to inspect image layers"}} docker/images -.-> lab-555153{{"How to use docker image history command to inspect image layers"}} end

View the history of a Docker image

In this step, you will learn how to view the history of a Docker image. The history of an image shows you the layers that make up the image and the commands that were used to create each layer. This is useful for understanding how an image was built and for debugging issues.

First, let's pull a Docker image that we can inspect. We will use the ubuntu image for this example.

docker pull ubuntu

You should see output indicating that the image is being pulled. Once the pull is complete, you can view the history of the image using the docker history command followed by the image name or ID.

docker history ubuntu

The output of the docker history command will show you a table with several columns:

IMAGE: The ID of the image layer.
CREATED: The time when the layer was created.
CREATED BY: The command that was used to create the layer.
SIZE: The size of the layer.
COMMENT: Any comment associated with the layer.

This history allows you to trace back the steps taken to build the ubuntu image, showing each command executed and the resulting layer.

View history with truncated output disabled

In the previous step, you viewed the history of the ubuntu image. You might have noticed that some of the output, particularly the commands in the CREATED BY column, were truncated. This is the default behavior of docker history to keep the output concise.

To view the full output without truncation, you can use the --no-trunc flag with the docker history command.

Let's try this with the ubuntu image.

docker history --no-trunc ubuntu

Now, you should see the complete commands that were used to create each layer of the ubuntu image. This can be very helpful when you need to see the exact details of how a layer was built, especially for complex images with long build commands.

Compare the output of this command with the output from the previous step to see the difference in the CREATED BY column.

View history with quiet output

In the previous steps, you saw the detailed history of the ubuntu image, including the commands used to create each layer. Sometimes, you might only be interested in the image IDs of the layers, without all the other information.

To view a more concise output that only shows the image IDs, you can use the -q or --quiet flag with the docker history command.

Let's view the history of the ubuntu image in quiet mode.

docker history -q ubuntu

The output will now only list the image IDs of the layers, one per line. This can be useful when you need to quickly get a list of layer IDs for scripting or other purposes.

Compare this output with the previous outputs to see how the -q flag simplifies the information displayed.

Format the history output using a Go template

In addition to the default and quiet output formats, docker history allows you to format the output using a Go template. This gives you fine-grained control over which information is displayed and how it is presented.

The --format flag is used to specify the Go template. You can access various fields of the image history using template syntax. Some common fields include .ID, .Created, .CreatedBy, .Size, and .Comment.

Let's try formatting the output to show only the image ID and the command used to create the layer, separated by a tab.

docker history --format "{{.ID}}\t{{.CreatedBy}}" ubuntu

In this template:

{{.ID}} refers to the image ID of the layer.
\t is a tab character for separation.
{{.CreatedBy}} refers to the command used to create the layer.

You can experiment with different fields and formatting to get the output you need. For example, to include the size:

docker history --format "{{.ID}}\t{{.Size}}\t{{.CreatedBy}}" ubuntu

Using Go templates provides a powerful way to extract specific information from the image history for scripting or reporting purposes.

Show history for a specific platform

Docker images can be built for different architectures and operating systems. When an image is available for multiple platforms, you might want to view the history for a specific platform.

The docker history command allows you to specify the target platform using the --platform flag. The format for the platform is typically os/architecture. For example, linux/amd64 or linux/arm64.

Let's view the history of the ubuntu image specifically for the linux/amd64 platform.

docker history --platform linux/amd64 ubuntu

The output will show the history of the ubuntu image built for the linux/amd64 architecture. If the image is not available for the specified platform, you might see an error or a different history depending on how the image was built.

This is particularly useful when working with multi-architecture images and you need to inspect the build process for a specific target environment.

Summary

In this lab, you learned how to use the docker history command to inspect the layers of a Docker image. You started by pulling the ubuntu image and then viewing its history, which displays information about each layer including the image ID, creation time, the command used to create it, and its size. This provides a clear view of the image's build process.

You then explored options to modify the output of docker history. You learned how to disable output truncation using the --no-trunc flag to view the complete commands used to build each layer. This is crucial for understanding the exact steps involved in image creation. The lab also covers viewing history with quiet output using the -q flag to show only image IDs, formatting the output with a Go template for customized views, and showing history for a specific platform using the --platform flag.