Extract Layer Data with docker image history

Somebody asks what is actually inside an image, and docker image history is the command that answers without a rebuild. You will inspect how a local image was assembled, identify the layer sizes and recorded creation commands, and produce machine-friendly output when needed. The examples use Docker Community Edition CLI 29.8.1, installed here as package docker-ce-cli version 5:29.8.1-1~ubuntu.24.04~noble. Allow about ten minutes. You need a Docker CLI connected to a daemon and an image that is already available locally.

1. Check the installed command

Start with a read-only version and help check. The command has two equivalent spellings: the documented form is docker image history, and docker history is its alias.

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker image history --help
Usage:  docker image history [OPTIONS] IMAGE

Show the history of an image

The final argument is one image reference or ID. Use the exact tag you mean, such as hello-world:latest, rather than assuming that a similarly named local tag points to the same image.

$ docker image ls hello-world
REPOSITORY    TAG       IMAGE ID       CREATED        SIZE
hello-world   latest    5e2309035332   6 months ago   16.4kB

Your ID, date and size will differ. If the list is empty, history cannot inspect that reference from this daemon. A permission error usually means your account cannot access the Docker socket. Ask an administrator to grant the appropriate access, or use sudo docker ... if that is the established policy on the host. Do not add sudo automatically: membership of the Docker group is itself highly privileged.

2. Read the default table

Run the command without options to get the useful first view:

$ docker image history hello-world:latest
IMAGE          CREATED        CREATED BY                SIZE      COMMENT
5e2309035332   6 months ago   CMD ["/hello"]            0B        buildkit.dockerfile.v0
<missing>      6 months ago   COPY hello / # buildkit   16.4kB    buildkit.dockerfile.v0

Rows describe the image's parent layers, with the image's top layer first. The CREATED BY value is recorded layer metadata, not a guaranteed reconstruction of the original Dockerfile. SIZE is the contribution of that layer, so it is normal for a command such as CMD to have a zero-byte layer. The total uncompressed image size shown by docker image ls is a different number from any one row.

The default output is human-readable: dates are relative and sizes use units such as kB. Docker CLI 29.8.1 reports --human as enabled by default. This makes the table easy to scan, but relative dates are a poor choice for an audit record.

3. Reveal truncated history

Long image IDs and commands are shortened in the table. Add --no-trunc when you need to distinguish layers or read the complete recorded command:

$ docker image history --no-trunc hello-world:latest
IMAGE                                                                    CREATED        CREATED BY
sha256:5e23090353324d887c48ad5e5c56d294eab81588df9605b07d1afe895f9cc8f8  6 months ago   CMD ["/hello"]
<missing>                                                                6 months ago   COPY hello / # buildkit

The exact table includes further columns, and your output will have different timestamps. The useful check is that the first ID is no longer shortened. Do not treat a displayed command as proof that a secret was not used during a build: history can omit details, and build arguments or other metadata may be handled elsewhere.

4. Choose the platform variant

A multi-platform image can contain separate histories. Use --platform with an operating system and optional architecture and variant, for example linux/amd64 or linux/arm64/v8:

$ docker image history --platform linux/amd64 hello-world:latest
IMAGE          CREATED        CREATED BY                SIZE      COMMENT
5e2309035332   6 months ago   CMD ["/hello"]            0B        buildkit.dockerfile.v0
<missing>      6 months ago   COPY hello / # buildkit   16.4kB    buildkit.dockerfile.v0

Without --platform, Docker selects the daemon's native platform where available, otherwise an available variant according to the daemon's rules. If the requested variant is not present in the local image store, the command fails rather than silently showing another platform. For example, asking the local hello-world image for linux/s390x here returns an error saying that the image does not provide that platform.

5. Extract IDs or selected fields

Use -q or --quiet when a script needs only the layer IDs:

$ docker image history --quiet hello-world:latest
5e2309035332
<missing>

Some parent layers have no local content ID in the image metadata, so <missing> is a meaningful result, not a shell error. Do not pass this output directly to a command that expects every line to be a usable image ID without filtering it.

For selected fields, use a Go template. Quote the template with single quotes in a POSIX shell so the shell does not interpret its braces:

$ docker image history --format '{{.ID}} {{.CreatedAt}} {{.Size}}' hello-world:latest
5e2309035332 2026-03-23T21:33:59Z 0B
<missing> 2026-03-23T21:33:59Z 16.4kB

The installed command documents .ID, .CreatedSince, .CreatedAt, .CreatedBy, .Size and .Comment. .CreatedSince follows the human-readable setting; .CreatedAt gives a timestamp and is usually the better field for repeatable reports. Add --human=false if you need non-human-readable dates or sizes, then verify the result against the version of Docker you are running.

For structured records, the installed CLI also accepts --format json:

$ docker image history --format json hello-world:latest
{"Comment":"buildkit.dockerfile.v0","CreatedAt":"2026-03-23T21:33:59Z","CreatedBy":"CMD [\"/hello\"]","CreatedSince":"6 months ago","ID":"5e2309035332","Size":"0B"}

Each history row is emitted as a JSON object. Parse it with a JSON-aware tool in a script instead of splitting the table on whitespace, because commands and comments can contain spaces.

6. Diagnose the common failures

No such image means the reference is not available to the connected daemon. Check spelling and tags with docker image ls. If the image is meant to come from a registry, pulling it changes local state and may download a large image, so confirm the registry, tag and disk space before running a pull:

$ docker image ls --format 'table {{.Repository}}\t{{.Tag}}\t{{.ID}}'
REPOSITORY    TAG       IMAGE ID
hello-world   latest    5e2309035332

An error about a platform means the requested variant is absent or does not match the local image. Check what is present with your image-listing tools and retry with a platform you actually have. A history lookup does not download a missing variant.

If output is unexpectedly short, first retry with --no-trunc. If dates are unsuitable for a report, use .CreatedAt or disable human-readable formatting. If a build command contains sensitive values, redact the captured output before sending it elsewhere.