Here’s a complete tutorial on docker history, covering what it does, examples, and use cases.

---

What is docker history?

docker history is a Docker command used to show the history of an image. It provides information about each layer in the image, including the creation time, size, command used, and author.

Key Features:

• Displays the layer-by-layer history of a Docker image.
• Helps in troubleshooting, auditing, and optimizing image builds.
• Useful for identifying image size contributors and build steps.

---

Basic Syntax

docker history [OPTIONS] IMAGE

Options:

• --no-trunc: Show the full output without truncating commands or IDs.
• --quiet, -q: Show only image IDs.
• --format: Format the output using Go templates (e.g., {{.CreatedBy}}).

---

Examples of docker history

1. Show History of an Image

docker history nginx:latest

Example Output:

IMAGE          CREATED        CREATED BY                                      SIZE      COMMENT
e21c333399e4   1 hour ago     /bin/sh -c apt-get update && apt-get install   45.2MB    Added dependencies
<missing>      1 day ago      /bin/sh -c #(nop) CMD ["nginx" "-g" "daemon…   0B
<missing>      1 day ago      /bin/sh -c #(nop) EXPOSE 80                   0B

---

2. Show Full Command Information (--no-trunc)

docker history nginx:latest --no-trunc

This displays the full command and image ID without truncation.

---

3. Show Only Image IDs (--quiet)

docker history -q nginx:latest

Example Output:

e21c333399e4
<missing>
<missing>

---

4. Use Custom Formatting

docker history --format "Created: {{.CreatedSince}}, Size: {{.Size}}, Command: {{.CreatedBy}}" nginx:latest

Example Output:

Created: 1 hour ago, Size: 45.2MB, Command: /bin/sh -c apt-get update
Created: 1 day ago, Size: 0B, Command: /bin/sh -c #(nop) CMD ["nginx" "-g"…

---

5. Show History for a Specific Image Tag

docker history my_app:1.0

This shows the history of my_app with the 1.0 tag.

---

6. Compare History of Two Images

docker history my_app:1.0
docker history my_app:2.0

This lets you compare layers to see what has changed between two versions.

---

7. Inspect Base Image Layers

docker history python:3.9

Check the history of the python:3.9 image to see how it was built.

---

8. Use in a Script for Audit Logs

#!/bin/bash
docker history my_image --format "Layer: {{.ID}}, Size: {{.Size}}, Command: {{.CreatedBy}}" > history_log.txt
echo "Image history saved to history_log.txt"

---

Use Cases for docker history

1. Auditing and Security

• Audit Docker images to see how they were built and identify suspicious layers.
• Example: Detect if unnecessary or malicious commands were executed during image creation.

2. Optimizing Docker Images

• Identify large layers that contribute to the image size and optimize them.
• Example: Consolidate RUN commands to reduce image layers.

3. Debugging Build Issues

• Check the history to trace build errors and understand how each layer was created.
• Example: Find out which layer failed during the build and fix the corresponding step in the Dockerfile.

4. Comparing Image Versions

• Compare the history of different image tags to see what has changed between versions.
• Example: Ensure that production images do not contain development tools or debug layers.

5. Understanding Base Images

• Inspect the history of a base image to learn about its structure and configuration.
• Example: Check which packages are installed in an official alpine or ubuntu image.

6. Automating Documentation and Audits

• Use docker history in automation scripts to log and document image changes.

---

List of Common docker history Commands

Command	Description
docker history nginx:latest	Show the history of the nginx:latest image
docker history my_app:1.0	Show history for a specific image tag
docker history --no-trunc my_app:1.0	Show full command and image IDs
docker history --format "{{.CreatedBy}}" my_app	Show only the commands used in each layer
docker history -q nginx:latest	Show only the image IDs for each layer
docker history python:3.9	Inspect the history of the python:3.9 base image
docker history --format "Size: {{.Size}}" my_app	Show only the size of each layer

---

Best Practices for Using docker history:

1. Regularly audit image history for security and compliance.
2. Use custom formatting (--format) to filter and display relevant information.
3. Optimize image size by identifying large layers and consolidating commands in your Dockerfile.
4. Document image changes by saving the history to a file and including it in your CI/CD pipelines.
5. Compare different image versions to track changes over time.

---

Common Errors and Solutions

1. “No such image”
   → Ensure the image exists by running docker images to list available images.
2. “Output truncated”
   → Use --no-trunc to display the full output without truncation.
3. Large output size
   → Use --format to filter and customize the output for easier readability.

---

Combining docker history with Other Commands

Analyze Image Size and Optimize Layers

docker history my_app:latest --format "Layer: {{.ID}}, Size: {{.Size}}, Command: {{.CreatedBy}}"

Save Image History for Documentation

docker history my_app:latest > history_log.txt

Identify Suspicious Commands in an Image

docker history my_app | grep "curl" | grep "wget"

---