Table of Contents
Why Inspect Containers
When something behaves unexpectedly in a container, you often need to see how it is configured and what Docker knows about it. Inspecting a container means asking Docker for the complete, structured description of that container. This includes its configuration, networking setup, storage details, and current state. Inspection is not about viewing logs or running commands inside the container, it is about asking the Docker Engine what it knows.
Inspection is especially useful when containers fail to start, when ports are not reachable, when volumes do not seem to be mounted, or when environment variables do not appear to be set correctly. Instead of guessing, you use inspection to confirm the exact configuration that is in effect.
The `docker inspect` Command
The primary tool for inspecting containers is the docker inspect command. It returns a detailed JSON document for one or more objects. You can inspect containers, images, networks, and other types, but in this chapter the focus is on containers.
The basic form is:
docker inspect <container-id-or-name>
If you do not specify any options, Docker prints the full JSON structure. This output can be long because it covers many aspects of the container, such as its image reference, created time, path and arguments, mounts, network settings, restart policy, and more.
Rule: Use docker inspect <name-or-id> to retrieve the complete JSON description of a container as known by the Docker Engine.
Because the output is valid JSON, it is structured and nested. This is ideal for tools and scripts but can be overwhelming to read directly in a terminal. The next sections focus on extracting only what you need.
Using `--format` to Extract Specific Fields
In practice you rarely need the entire JSON document. It is more common to want a single field or a small group of values. Docker provides the --format option, which uses Go template syntax to select specific pieces of the JSON.
The pattern is:
docker inspect --format '{{ .Field.SubField }}' <container>
Here .Field.SubField describes the path into the JSON object. Fields are case sensitive and must match the internal structure.
For example, to see the container ID only, you might select:
docker inspect --format '{{ .Id }}' <container>
To avoid dealing with very long lines, especially for complex structures, you can focus on key properties like name, state, or network information. Using --format turns docker inspect into a precise query tool rather than a general dump.
Rule: Use docker inspect --format 'TEMPLATE' to filter the JSON and print only the fields you need.
This is extremely useful inside scripts, where you might want to capture a single value and use it in another command, such as a container IP address or a mount path.
Checking Container State and Status
When a container does not behave as expected, the first question is often whether it is actually running. Although there are other commands for listing containers, docker inspect gives the authoritative state and related details.
The state of a container is stored under .State. It includes its current status, exit code, start and finish times, and whether it has ever been restarted. For example, you can query:
docker inspect --format '{{ .State.Status }}' <container>
Typical values include created, running, exited, paused, or restarting. Knowing the precise state helps you distinguish between a container that never started and one that started and then exited immediately.
The exit code is also valuable, especially in debugging:
docker inspect --format '{{ .State.ExitCode }}' <container>
An exit code of zero usually indicates success, while a nonzero exit code indicates an error defined by the process inside the container.
Rule: Inspect .State.Status and .State.ExitCode to understand whether a container is running and why it may have stopped.
These fields complement other debugging tools, such as logs and resource usage details, and they give you a clear picture of the lifecycle of the container.
Viewing Environment Variables and Command
Sometimes a container behaves differently from what you expect because of its environment or start command. The configuration that Docker actually uses may not match what you think you specified. docker inspect reveals the environment variables, working directory, and exact command line in effect.
The command is represented under .Config.Cmd and, when combined with entrypoint, defines what runs inside the container. For example:
docker inspect --format '{{ .Config.Cmd }}' <container>
You can also check the entrypoint in a similar way. This helps confirm which process is responsible for the container behavior you observe.
Environment variables are found under .Config.Env. They are stored as a list of strings of the form KEY=VALUE. Because this can be a long list, you might want to print them all to review or feed them to another tool.
Rule: Use docker inspect to confirm the effective environment and command of a container instead of relying only on what you intended to configure.
By comparing the inspected configuration to your expectations, you can quickly identify misconfigurations such as missing environment variables or incorrect arguments.
Inspecting Networking Details
Networking problems are common when first working with containers. A service might be listening inside the container but not reachable from your host or from other containers. docker inspect shows the network configuration that Docker is actually using, and this is crucial for diagnosing such issues.
Network related information is available under .NetworkSettings. This includes the container IP address on each network, the network names, and the exposed ports. For simple cases, the IP address within the default bridge network can be read with a template like:
docker inspect --format '{{ .NetworkSettings.IPAddress }}' <container>
If the container is attached to user defined networks, or multiple networks, the information is nested under .NetworkSettings.Networks. You can inspect that substructure directly or refine the template further when you need a specific network.
Port bindings, which connect container ports to host ports, are stored under .NetworkSettings.Ports. Although this structure can be complex for many ports, it is the authoritative source for seeing which ports are truly mapped.
Rule: Always inspect .NetworkSettings when troubleshooting connectivity between containers or between a container and the host.
By verifying the networks and port mappings at the Docker level, you avoid making assumptions about how traffic should flow and you can correlate this data with other networking tools.
Understanding Volumes and Mounts
Data handling is another area where expectations often differ from reality. A container might appear to ignore a bind mount, or data might not persist as intended. To see how Docker has actually attached storage to a container, you can inspect its mounts.
Mount information appears under .Mounts. Each mount entry describes the type, such as a volume or bind, the source path on the host, and the destination path inside the container. This lets you verify whether the correct host directory or named volume is in use, and whether it is mounted at the location you expect.
For example, if you suspect that your application is writing to the wrong directory, you can check the mounts to ensure that the intended directory is indeed mounted into the container.
Rule: Inspect .Mounts to confirm which volumes and bind mounts are attached to a container and where they appear inside it.
By relying on inspected mount information instead of assumptions or documentation, you can debug data persistence and sharing issues much more effectively.
Using Inspection in Everyday Workflows
docker inspect is not limited to deep debugging sessions. It is also helpful during normal development and operations work as a quick verification tool. When you inherit an existing environment, or when you work with containers created by others or by automation tools, inspection lets you see the exact configuration without guessing.
Typical everyday uses include verifying that a container was started with the correct image, confirming the restart policy via .HostConfig.RestartPolicy, or checking labels that may influence orchestration or monitoring. Because the JSON includes both configuration and runtime state, it can serve as a precise documentation of what is currently deployed.
Combining docker inspect with shell tools or scripting languages enables automated checks. For example, a script can inspect containers and alert if certain configurations are missing, or extract addresses and ports to build dynamic configuration files for other services.
The key habit is to treat docker inspect as a direct window into what Docker knows and uses for a container. Whenever something about a container is unclear, inspection provides the authoritative source of truth.