Docker commands Guide – docker history with examples

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
Code language: CSS (css)

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
Code language: CSS (css)

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
Code language: HTML, XML (xml)

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

docker history nginx:latest --no-trunc
Code language: CSS (css)

This displays the full command and image ID without truncation.

3. Show Only Image IDs (--quiet)

docker history -q nginx:latest
Code language: CSS (css)

Example Output:

e21c333399e4
<missing>
<missing>
Code language: HTML, XML (xml)

4. Use Custom Formatting

docker history --format "Created: {{.CreatedSince}}, Size: {{.Size}}, Command: {{.CreatedBy}}" nginx:latest
Code language: JavaScript (javascript)

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"…
Code language: JavaScript (javascript)

5. Show History for a Specific Image Tag

docker history my_app:1.0
Code language: CSS (css)

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
Code language: CSS (css)

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

7. Inspect Base Image Layers

docker history python:3.9
Code language: CSS (css)

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"
Code language: PHP (php)

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

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}}"
Code language: JavaScript (javascript)

Save Image History for Documentation

docker history my_app:latest > history_log.txt
Code language: CSS (css)

Identify Suspicious Commands in an Image

docker history my_app | grep "curl" | grep "wget"
Code language: JavaScript (javascript)

Rajesh Kumar

I’m Rajesh Kumar, a DevOps, SRE, DevSecOps, Cloud, and Platform Engineering expert passionate about sharing practical knowledge, real-world experiences, and industry best practices. I have worked at Cotocus and regularly write about technology, travel, investing, health, product reviews, and digital marketing through my various platforms.

I publish technical articles at DevOps School, travel stories at Holiday Landmark, stock market insights at Stocks Mantra, health and fitness guidance at My Medic Plus, product reviews at TrueReviewNow, and SEO and digital marketing strategies at Wizbrand.