Inspecting an image · Docker & Containers

Every layer is a tar archive answering one question: what changed between this layer and the one below it. Inspecting an image layer by layer is the fastest route to “why is this 1.2 GB” and “where did that file come from” — and the second of those questions has security consequences that surprise people.

Three tools, three questions:

Question	Tool
What will this image do when it runs?	`docker image inspect`
Which build step produced which layer, and how big?	`docker image history`
Which file is taking the space?	`dive`, or `docker save` and `tar`

`docker image inspect` — the runtime contract

Read-only / Safethe useful fields— One call, the four things a reviewer actually needs.

$ docker image inspect nginx:1.27 --format 'user={{.Config.User}} entry={{json .Config.Entrypoint}} cmd={{json .Config.Cmd}} health={{if .Config.Healthcheck}}yes{{else}}none{{end}}'

user= entry=["/docker-entrypoint.sh"] cmd=["nginx","-g","daemon off;"] health=none

Illustrative output

An empty user= is the single most common finding in an image review: the container will run as root unless the runtime overrides it, because no USER instruction was ever set.

The fields worth knowing, and what each is for:

Field	Use
`.Id`	Local identity — the config JSON hash
`.RepoDigests`	Remote identity — what the registry served
`.RootFS.Layers`	Layer diff_ids (uncompressed), not the manifest’s blob digests
`.Config.User`	Runs as root if empty
`.Config.Env`	Everything baked into the environment, including mistakes
`.Config.Healthcheck`	Absent means the orchestrator has nothing to work with
`.Config.ExposedPorts`	Documentation only — it publishes nothing
`.Config.Labels`	Ownership, source commit, build metadata
`.Architecture`, `.Os`	What this image actually is, versus what you expected
`.Size`	Sum of layer sizes, uncompressed on disk

The environment variable somebody left in the image

.Config.Env is worth reading in full on every image you did not build, because of what routinely ends up there.

A build that does ENV DATABASE_URL=... or ARG NPM_TOKEN followed by ENV NPM_TOKEN=$NPM_TOKEN has written that value into the image config — a plain-text JSON document that ships to the registry and that anybody who can pull the image can read, with no need to run it:

docker image inspect --format '{{json .Config.Env}}' myapp:1.0

They do not even need Docker. crane config myapp:1.0 fetches the config blob straight from the registry.

The wrong fix, and the one people reach for, is a later ENV VAR= or an unset. Neither removes it — the value is in the config history and in the layer metadata regardless. The only remedies are to rebuild without ever setting it and rotate the credential. Build-time secrets belong in RUN --mount=type=secret, which never lands in a layer.

`docker image history` — where the size went

Read-only / Safehistory— Each row is a layer. The SIZE column is what that step added.

$ docker image history myorg/myapp:1.0 --no-trunc --format 'table {{.Size}}\t{{.CreatedBy}}'

SIZE      CREATED BY
0B        CMD ["node" "server.js"]
0B        EXPOSE map[3000/tcp:{}]
412MB     RUN /bin/sh -c npm install
1.2kB     COPY package.json ./ # buildkit
0B        WORKDIR /app
0B        /bin/sh -c #(nop)  CMD ["node"]
77.8MB    /bin/sh -c #(nop) ADD file:... in /

Illustrative output

Two features of this output cause confusion every time.

Rows with 0B are metadata, not layers. CMD, ENV, EXPOSE, WORKDIR, LABEL and USER change the config JSON and create no filesystem content. They still appear as history entries.

The IMAGE column is mostly <missing>. On a pulled image, or one built with BuildKit, the daemon has no local image ID for the intermediate steps, because those intermediate configs were never created on this host. <missing> means exactly that and nothing more — it is not corruption, and it is not a sign the image is broken. It does mean you cannot docker run an intermediate layer to poke around in it, which is the technique people are usually reaching for when they notice.

The `rm -rf` that did not shrink the image

The most common size mistake in Docker, and it is fully explained by layering.

RUN apt-get update && apt-get install -y build-essential
RUN rm -rf /var/lib/apt/lists/*        # a separate layer

The image does not get smaller. It gets larger — you added a layer.

Each layer records changes relative to the one below it. A file deleted in a later layer is recorded as a deletion marker; the file itself is still present, in full, in the earlier layer, and every pull still transfers it. The storage driver documentation puts it plainly for the equivalent case: the directory “is removed, but will still be available in the previous layer and add up to the image’s total size.”

The tell in docker history is a large RUN row followed by a 0B or near-0B cleanup row. The cleanup did nothing to the size.

The fix is to never create the file in a layer you keep — clean up inside the same RUN:

RUN apt-get update \
 && apt-get install -y --no-install-recommends build-essential \
 && rm -rf /var/lib/apt/lists/*

The security version of this is worse than the size version. A secret copied in and deleted in a later step is still in the earlier layer, recoverable by anybody who pulls the image. docker history will not show it; the section below will.

Reading a layer directly

You do not need a third-party tool for this, and knowing the manual route matters because it is what works on a hardened host, in an air-gapped environment, or when you are auditing an image you do not trust enough to run.

Read-only / Safeextract— Unpack an image to a temporary directory and inspect its layers as ordinary tar files.

IMAGE=myorg/myapp:1.0
WORK=$(mktemp -d)

docker save "$IMAGE" | tar -x -C "$WORK"

# Layer blobs, largest first.
find "$WORK" -name '*.tar' -o -path '*blobs*' -type f \
| xargs -r du -h 2>/dev/null | sort -rh | head -5

# What is inside the biggest one, without extracting it.
BIG=$(find "$WORK" -path '*blobs*' -type f -printf '%s %p\n' \
    | sort -rn | head -1 | cut -d' ' -f2)
tar -tvf "$BIG" 2>/dev/null | sort -k3 -rn | head -20

rm -rf "$WORK"

That last pipeline — list a layer’s contents sorted by size — is the answer to “what single file is making this image huge”, and it also finds the .env file, the private key, and the .git directory that a careless COPY . . swept in.

Read-only / Safedive— Host-installed binary. No socket handed to a container.

# Install from the project's releases, then:
IMAGE=myorg/myapp:1.0
dive "$IMAGE"

# Non-interactive: fail a build whose layer efficiency is below a threshold.
CI=true dive "$IMAGE" --lowestEfficiency 0.95

`docker image inspect` versus the remote tools

docker image inspect requires the image to be on the host. That is a real constraint in CI, on a jump host, and when you are triaging an image you would rather not pull.

Read-only / Safelocal vs remote— The same questions, answered without pulling anything.

IMAGE=nginx:1.27

# Local. Requires a pull. Gives the runtime config and the diff_ids.
docker image inspect "$IMAGE" --format '{{.Config.User}} {{.Architecture}}'

# Remote. Pulls only the manifest. Shows platforms and the index digest.
docker buildx imagetools inspect "$IMAGE"

# Remote. Pulls only the config blob — a few kilobytes for any image.
crane config "$IMAGE" | jq '{ user: .config.User,
                            entrypoint: .config.Entrypoint,
                            env: .config.Env,
                            layers: (.rootfs.diff_ids | length) }'

crane config on a 2 GB image transfers a few kilobytes, because the config JSON is a separate small blob. For a policy check that runs against every image in a registry, that difference is the whole feasibility of the exercise.

Why `.Size` and `docker images` disagree with the registry

Three different numbers describe “how big is this image”, and they are all correct.

.Size from docker image inspect is the sum of the uncompressed layer sizes, which is roughly the disk footprint under /var/lib/docker/overlay2.
The registry’s number is the sum of the compressed blob sizes, which is what a pull transfers. It is typically a third to a half of .Size.
docker system df reports shared and unique size, because layers are shared between images. Ten images on the same base do not cost ten times the base.

That last one is why “delete the big image to free space” so often frees almost nothing: most of its bytes were the base layer, and three other images still reference it. docker system df -v shows per-image shared and unique sizes, and the unique column is the only one that predicts what you will actually reclaim.

Note also that .RootFS.Layers lists diff_ids — the digests of the uncompressed tars — while the registry manifest lists the digests of the compressed blobs. Same layers, same order, different hashes. Trying to match a local layer to a registry blob by digest fails for this reason and not because anything is wrong.

Inspection as a gate

The point of all this is a check that runs before a deployment and fails.

Read-only / Safepolicy gate— Reject an image that runs as root, has no healthcheck, or leaks a credential-shaped variable.

IMAGE=$1
FAIL=0

USER_SET=$(docker image inspect --format '{{.Config.User}}' "$IMAGE")
if [ -z "$USER_SET" ] || [ "$USER_SET" = "root" ] || [ "$USER_SET" = "0" ]; then
  echo "FAIL $IMAGE runs as root (Config.User is empty or root)" >&2
  FAIL=1
fi

if ! docker image inspect --format '{{if .Config.Healthcheck}}ok{{end}}' "$IMAGE" | grep -q ok; then
  echo "WARN $IMAGE declares no HEALTHCHECK" >&2
fi

if docker image inspect --format '{{range .Config.Env}}{{println .}}{{end}}' "$IMAGE" \
 | grep -Eiq '(TOKEN|SECRET|PASSWORD|_KEY)='; then
  echo "FAIL $IMAGE has a credential-shaped environment variable baked in" >&2
  FAIL=1
fi

OWNER=$(docker image inspect --format '{{index .Config.Labels "org.opencontainers.image.source"}}' "$IMAGE" 2>/dev/null)
if [ -z "$OWNER" ]; then
  echo "FAIL $IMAGE has no org.opencontainers.image.source label" >&2
  FAIL=1
fi

exit "$FAIL"

Each of those is a real finding somebody has shipped. The grep for credential-shaped variables in particular finds things regularly, and it costs nothing to run on every image in a registry.

What happens if you inspect an image built for a different architecture?

Nothing dramatic, and that is the problem — it inspects cleanly and tells you the truth in a field nobody reads.

docker image inspect reports .Architecture and .Os for whatever platform-specific manifest the pull selected. On a multi-platform image, that is the entry your host matched. So the same command on an amd64 CI runner and an arm64 laptop returns different .Id values, different layer diff_ids, and different sizes — for the same tag.

This is exactly right and routinely misread as image corruption or a broken cache, because the two engineers comparing notes are looking at two different manifests without knowing it.

Two habits keep it straightforward. Always print .Architecture alongside anything you are comparing:

docker image inspect --format '{{.Architecture}}/{{.Os}} {{.Id}}' "$IMAGE"

And when you need to inspect a specific platform rather than the one your host happened to select, ask for it explicitly rather than relying on the default — docker image history --platform linux/arm64 takes a platform, and crane config --platform linux/arm64 fetches the config for the entry you name without pulling anything.

Why this matters

Image inspection is the cheapest quality gate that exists. “Why is this image 1.2 GB” is answered by docker history in ten seconds. “Does this run as root” is one field. “Is there a token baked into this” is one grep, and it finds something more often than anybody is comfortable with.

The layer model is the part worth internalising, because it is counter-intuitive in a way that costs real money and real incidents. A file you deleted is still shipped. A secret you removed is still readable. A cleanup step you added made the image bigger, not smaller. None of that is visible from the Dockerfile, and all of it is obvious once you look at the layers.

Thirty seconds of inspection before an image reaches a registry is cheaper than every downstream consequence of not doing it — and unlike most quality practices, it is entirely mechanical and can be run by a script on everything you already have.

docker image inspect — the runtime contract

docker image history — where the size went

Reading a layer directly

docker image inspect versus the remote tools

Inspection as a gate

Knowledge check

`docker image inspect` — the runtime contract

`docker image history` — where the size went

`docker image inspect` versus the remote tools