Container images

What is inside your container image? Follow the layers.

Inspect an OCI or Docker-save archive locally, follow file additions and whiteouts, and understand what image-size numbers actually measure.

By Buddy Code 28 October 2026

A file can disappear from a container’s final filesystem while its original bytes remain in an earlier image layer. That distinction matters when you are checking an unexpected build artifact, tracing a removed file or trying to understand a large image.

The OCI image archive inspector lets you follow those changes in a local archive. It reads the supplied image data in your browser, without starting a container, connecting to a registry or writing archive members to disk. Start with the built-in example before selecting a real export.

Open OCI image archive inspector →

An image is a sequence of filesystem changes

A layer records additions, replacements and removals relative to the layers below it. Applying the layers in order produces the final filesystem view. Listing one layer alone therefore answers a different question from listing the files visible after all layers have been applied.

An OCI layout contains an index, image metadata and content-addressed blobs. An archive may describe several images, so first choose the image you intend to examine. The inspector also accepts supported Docker-save archives; a similarly named TAR file is not automatically a supported image export.

Reference: OCI image specification: layer changes and whiteouts; OCI image specification: image layout

Follow a two-layer example

Open the inspector and choose Inspect local example. No file or account is required.
Select Layer 1 in Layer changes. Find app/old.txt and app/keep.txt: these paths enter the image in the first layer.
Select Layer 2. Look for the removal of app/old.txt and the addition of app/new.txt.
Check Final paths. app/keep.txt and app/new.txt remain; app/old.txt no longer appears in that final view.

A simplified view of the example’s changes

Layer 1
  + app/old.txt
  + app/keep.txt

Layer 2
  - app/old.txt  (whiteout)
  + app/new.txt

Final paths
    app/keep.txt
    app/new.txt

Repeat the same journey with your own supported archive: select the file, choose an image if prompted, then select Inspect archive. Use Filter paths to narrow the final list to a directory such as app/. When a result needs further investigation, download the JSON report to keep the layer-by-layer evidence alongside the build you examined.

Read a deletion as an instruction

OCI represents removals using special whiteout entries. For example, app/.wh.old.txt tells the layer consumer to remove app/old.txt from the lower-layer view. An opaque-directory marker, .wh..wh..opq, hides the lower-layer children of its containing directory. These markers do not become ordinary files in the final view.

The inspector applies whiteouts before the ordinary entries from the same layer. This distinction preserves newly supplied entries while removing the intended lower-layer paths. If a file is labelled replaced, the tool has seen the path supplied again; that label alone does not establish that its content differs.

Reference: OCI image specification: layer changes and whiteouts

Keep the size numbers separate

What the inspector’s byte counts describe
Number	Useful interpretation
Stored bytes	The layer blob’s stored size, including compression where applicable.
Expanded bytes	The uncompressed layer TAR size, including archive overhead.
Retained payload	Regular-file payload bytes represented in the final paths.
Superseded payload	An estimate of file payload hidden by later changes.

These quantities answer different questions. Superseded payload is not a promise of recoverable disk space, a predicted registry download saving or the size of a running container. Compression, archive headers, shared layers and filesystem behavior prevent that direct conversion. Use the numbers to locate a layer worth investigating, then measure the rebuilt image in its actual delivery environment.

Understand what verification can establish

An OCI descriptor digest identifies the referenced blob bytes. A layer DiffID identifies the uncompressed layer TAR, so those values can differ for compressed layers. The inspector verifies supported OCI SHA-256 descriptors and layer DiffIDs. Matching hashes establish consistency with the supplied metadata; they do not authenticate a publisher or certify that the image is safe to run.

The current input limit is 128 MiB, with separate limits of 256 MiB for the expanded outer archive, 128 MiB per layer, 512 MiB total layer expansion, 100 layers and 50,000 entries. Plain TAR and gzip are supported; zstd and sparse TAR are not. A small compressed input can still exceed an expansion limit.

The report tracks paths and link metadata. It does not resolve links, emulate device files or reproduce every runtime filesystem behavior. It is an inspection aid rather than a vulnerability scanner, signature verifier or container runtime. Keep the exported report private when its paths or image labels disclose internal project details.

Reference: OCI image specification: layer DiffID

Technical references

These primary sources explain the underlying formats and browser APIs. Tool-specific behavior and limits above describe the current Buddy Code implementation.

PUT IT INTO PRACTICE

Try it with your own setup.

Inspect local OCI and Docker-save archives, layer changes and the final path inventory without installing Docker.

Open OCI image archive inspector →

← All articles