Table of Contents
Looking Inside Docker Images
Inspecting a Docker image lets you see what it contains and how it is configured. This is essential when you need to understand where files are, what the default command is, or how the image was built. In this chapter you focus on tools and commands that reveal information about existing images.
Using `docker image inspect`
The primary way to inspect an image is with the docker image inspect command. It outputs detailed metadata in JSON format. This includes configuration, layers, environment variables, exposed ports, entrypoint, and other low level details.
The basic form is:
docker image inspect IMAGE_NAME_OR_ID
You can use a tag, such as nginx:latest, or an image ID. The result is a large JSON document. For a single image, Docker still prints a JSON array containing one object. If you inspect multiple images at once, you receive one JSON object for each image in the array.
You might not want to read the entire JSON every time. You can filter the output with the --format option, which uses Go templates to extract specific fields. For example, to show only the default command for an image:
docker image inspect nginx:latest --format '{{.Config.Cmd}}'
To list environment variables defined in the image:
docker image inspect nginx:latest --format '{{.Config.Env}}'
Or to see the working directory defined in the image:
docker image inspect nginx:latest --format '{{.Config.WorkingDir}}'
The JSON structure contains many useful sections. The Config section shows settings that come from the Dockerfile, such as the base user, environment variables, and entrypoint. The RootFS section lists image layers. The RepoTags and RepoDigests sections show how the image is referenced in registries.
Always prefer docker image inspect with --format when you need specific fields. This avoids scrolling through large JSON output and reduces the chance of missing important details.
Viewing Image History with `docker history`
While docker image inspect focuses on the current configuration, docker history reveals how an image was built layer by layer. This is especially useful when you want to understand why an image is large or which Dockerfile instructions produced each layer.
Run:
docker history IMAGE_NAME_OR_ID
The output is a table. Common columns include the image ID for each layer, the time when the layer was created, the size of the layer, and the command that created it. The command column often shows the corresponding Dockerfile instruction, such as RUN, COPY, or ADD.
If you see very large layers, you can trace them back to particular instructions. This helps when you later optimize image size in other chapters. For now, focus on interpretation. A single RUN instruction might create one layer, while multiple separate RUN instructions create multiple layers.
docker history usually truncates long commands to keep the table compact. If you want to see the full commands, you can use --no-trunc:
docker history --no-trunc IMAGE_NAME_OR_ID
This makes it easier to match each layer with its original Dockerfile line.
Use docker history to understand which Dockerfile instructions created which layers. Large or unexpected layers often indicate inefficient commands that can be improved in your Dockerfile.
Inspecting Files Inside an Image
Sometimes you need to check whether a particular file exists in an image, or you want to inspect configuration files or directory structure. You can do this by starting a temporary container from the image and running commands inside it.
One common pattern is:
docker run --rm -it IMAGE_NAME_OR_ID sh
This starts a container, opens a shell, and removes the container when you exit. Inside the shell you can use normal tools like ls, cat, or grep to explore the filesystem. If the image is based on a different operating system, the shell might be bash or another shell instead of sh.
If you do not need an interactive session, you can list files or inspect them directly with a one off command. For example, to list the root directory:
docker run --rm IMAGE_NAME_OR_ID ls /
Or to print a configuration file:
docker run --rm IMAGE_NAME_OR_ID cat /path/to/config
This approach gives a practical view of what is actually present in the image, not just what the metadata says.
When you only need to inspect, use --rm with docker run so that temporary containers are removed automatically. This keeps your environment clean and prevents unused containers from accumulating.
Extracting Specific Metadata for Scripts and Tools
In many workflows you want to use image metadata inside scripts or automation tools. The --format option of docker image inspect is particularly useful here, because you can output simple values that are easy to process.
For example, to get the image’s default user:
docker image inspect IMAGE_NAME_OR_ID --format '{{.Config.User}}'
To get the labels set on an image:
docker image inspect IMAGE_NAME_OR_ID --format '{{json .Config.Labels}}'
The {{json ...}} helper prints the labels as a JSON object, which is convenient to parse in most programming languages.
You can also combine fields. For example, to print the image’s entrypoint and command together in a human readable line:
docker image inspect IMAGE_NAME_OR_ID --format 'Entrypoint: {{.Config.Entrypoint}} Cmd: {{.Config.Cmd}}'
This style of inspection is especially powerful in build pipelines and CI systems, where you might, for example, enforce that all images have certain labels or verify that they use a specific base user.
When you build tooling around Docker images, always rely on docker image inspect --format instead of manually parsing raw JSON. Template based output is more stable and easier to consume in scripts.
Checking Exposed Ports and Environment Variables
Understanding which ports and environment variables an image defines helps you run containers correctly and connect them to other services.
To see exposed ports, use:
docker image inspect IMAGE_NAME_OR_ID --format '{{.Config.ExposedPorts}}'
This prints a map of ports such as map[80/tcp:{} 443/tcp:{}]. These ports indicate what the image declares, not what is actually published on the host. Publishing still depends on how you run the container with port mapping, which is covered elsewhere, but the exposed ports give you a hint about the intended usage.
To inspect environment variables:
docker image inspect IMAGE_NAME_OR_ID --format '{{.Config.Env}}'
You might see variables that control application behavior, such as PORT or database settings. When you run a container, you can override or extend these variables with -e or --env-file, which will be covered in other chapters. For inspection purposes, this metadata helps you know what is already set by the image.
If you prefer a more readable output, you can expand the environment variables line by line through shell tools, but the important part is that all base environment variables can be queried from the image without running a full interactive session.
Always inspect exposed ports and environment variables before running unfamiliar images. This reduces guesswork and helps you configure containers correctly on the first try.
Verifying Image Origins with Digests
Every image has a content digest that uniquely identifies its exact contents. While tags like latest can change, the digest remains the same for a specific image version. You can see an image’s digest through docker image inspect by looking at the RepoDigests field.
For a quick view, you can run:
docker image inspect IMAGE_NAME_OR_ID --format '{{.RepoDigests}}'
The result contains fully qualified references such as repository@sha256:.... These are especially important when you want to pin an image to a specific version in production environments. While this course covers tags and digests in more depth elsewhere, here you only need to know that inspection gives you access to these immutable identifiers.
You can also see digests when pulling images or through docker images --digests, but docker image inspect is the most direct way to check all digests associated with a given image in your local environment.
Use image digests when you need reproducible deployments. A digest identifies the exact image contents, while tags may move to newer versions over time.
Putting Inspection into Practice
In real workflows, you often combine several inspection techniques. You might start with docker history to see how the image was built, then use docker image inspect with targeted --format queries to extract environment variables, the working directory, and entrypoint. Finally, you might start a temporary container to confirm file locations.
This combination allows you to treat Docker images not as opaque artifacts but as transparent, inspectable units. When debugging, validating third party images, or preparing to create your own improved images, these skills become essential.
At this stage, you do not need to memorize every field in the JSON output. Instead, remember the key patterns: use docker image inspect for metadata, docker history for build layers, and temporary containers to explore the filesystem. This foundation will support more advanced image work in later chapters.