Introduction

Inspecting a Docker image can mean two different things: reading its metadata or browsing the filesystem it contains. The right command depends on whether you want build history, environment settings, or the actual files that will exist when a container starts.

Use docker image inspect for Metadata

If you want configuration details such as entrypoint, environment variables, working directory, or labels, start with:

docker image inspect nginx:latest

This returns JSON describing the image, including the command Docker will run and the layers it references. It is useful for debugging startup behavior, but it does not show you a directory listing of the image contents.

You can also filter the JSON with Go templates:

docker image inspect nginx:latest --format '{{.Config.WorkingDir}}'
docker image inspect nginx:latest --format '{{json .Config.Env}}'

That is often faster than scanning the full JSON blob.

Use docker history to Understand Layers

To see how the image was built, use:

docker history nginx:latest

This lists the layers, the commands that produced them, and the approximate size of each one. It does not show the final file tree directly, but it helps explain why the image is large or where a dependency was added.

For example, a large RUN apt-get install ... layer tells you the package set probably lives there.

Open a Shell in a Container for File Browsing

If your main goal is "show me the files", the most practical approach is to start a container and inspect its filesystem from inside.

docker run --rm -it nginx:latest sh

Once inside, use normal shell commands:

pwd
ls -la
find /etc/nginx -maxdepth 2 -type f

This method is easy, interactive, and usually the fastest way to answer questions such as where a config file lives or whether a package is installed.

If the image does not contain sh, try the executable it does provide, or create a container and inspect it externally instead.

Export the Filesystem Without Running the App

Sometimes you do not want to launch the default process at all. In that case, create a container, export its filesystem, and inspect the tar archive:

1docker create --name temp-inspect nginx:latest
2docker export temp-inspect -o image-files.tar
3tar -tf image-files.tar | head -50
4docker rm temp-inspect

This is useful in CI or when you want a complete file listing without entering an interactive shell.

It is important to know that docker export gives you the container filesystem view, not the original image layer structure.

Use docker save When You Need Layer-Level Detail

If you want the actual image archive with layers and metadata preserved, use docker save:

docker save nginx:latest -o nginx-image.tar
tar -tf nginx-image.tar | head -20

This output contains manifests and individual layer tar files. It is more detailed than docker export, but also more cumbersome when your goal is only to find a single config file.

In practice:

• Use docker export to inspect the final merged filesystem.
• Use docker save to inspect how the image is packaged internally.

Picking the Right Method

Different inspection goals call for different tools:

1docker image inspect my-image:latest
2docker history my-image:latest
3docker run --rm -it my-image:latest sh
4docker create --name tmp my-image:latest
5docker export tmp -o fs.tar

That sequence covers metadata, layer history, interactive browsing, and offline inspection.

Common Pitfalls

One common mistake is expecting docker image inspect to show file names. It only shows metadata. If you need directories and files, inspect the container filesystem instead.

Another pitfall is forgetting that minimal images may not include a shell. Distroless and scratch-based images are especially restrictive. In those cases, docker export or docker save is more reliable.

Users also confuse docker save and docker export. save preserves the image and its layers, while export flattens the container filesystem. They answer different questions.

Finally, remember to remove temporary containers after inspection or use --rm when possible.

Summary

• Use docker image inspect for configuration and metadata, not file listings.
• Use docker history to see how the image was built and where size comes from.
• Run a shell inside a container when you want the quickest interactive filesystem view.
• Use docker export for a flattened filesystem snapshot and docker save for layer-aware archives.
• Choose the inspection method based on whether you need metadata, history, or actual files.