Deep Container Diagnostics: Inspecting Configuration and State with docker inspect
Unlock detailed JSON state, network settings, volume mounts, and health data using docker inspect and Go template formatting.
Published on • November 17, 2026
AI Assistant

When troubleshooting container networking issues, verifying volume mounts, or checking health check status, command-line summary tools like docker ps don’t reveal the whole story.
The docker inspect command returns low-level system architecture configuration and runtime state for Docker objects (containers, images, volumes, networks) formatted as structured JSON.
In this tutorial, we will explore docker inspect’s JSON schema, demonstrate Go template formatting (--format), and share real-world diagnostic queries.
1. Basic Usage of docker inspect
Executing docker inspect with a container name or ID returns a comprehensive JSON array containing the object’s complete configuration:
docker inspect web-server
Inspected Object Types
docker inspect automatically detects the type of object provided. You can inspect:
- Containers:
docker inspect <container_id> - Images:
docker inspect <image_name> - Volumes:
docker inspect <volume_name> - Networks:
docker inspect <network_name>
To explicitly target a container object, use docker container inspect:
docker container inspect web-server
2. Key Sections of Container JSON Metadata
The returned JSON payload contains several top-level sections:
Id: Full 64-character SHA-256 hash.Created: ISO-8601 creation timestamp.State: Execution status details (Running,Paused,Restarting,ExitCode,OOMKilled,Pid,Error).Image: Image digest SHA-256 ID.HostConfig: Resource limits (CPU, memory), restart policies, port bindings, and cgroup rules set at runtime.Config: Environment variables (Env), exposed ports, volume definitions, entrypoint, cmd, and working directory.Mounts: List of active volumes and bind mounts mapped into the container.NetworkSettings: IP addresses, gateway, MAC address, and network bridge bindings across all connected Docker networks.
3. Filtering Output with Go Templates (--format)
Scanning hundreds of lines of raw JSON manually is inefficient. Use the --format flag with Go template syntax to query specific nested JSON attributes directly.
Extracting Container IP Address
docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web-server
Checking Container Health Status
If your container includes a HEALTHCHECK directive:
docker inspect --format '{{.State.Health.Status}}' web-server
Inspecting Exit Code and OOM Kill State
Determine if a container crashed due to an Out-Of-Memory (OOM) killer event:
docker inspect --format 'ExitCode: {{.State.ExitCode}}, OOMKilled: {{.State.OOMKilled}}' web-server
Listing Environment Variables
docker inspect --format '{{range .Config.Env}}{{println .}}{{end}}' web-server
Listing Volume Mount Mappings
docker inspect --format '{{range .Mounts}}{{.Source}} -> {{.Destination}} ({{.Mode}}){{end}}' web-server
4. Using jq for Advanced JSON Querying
While Go templates are natively built into Docker CLI, piping docker inspect output to jq offers flexible JSON parsing:
# Pretty-print container NetworkSettings
docker inspect web-server | jq '.[0].NetworkSettings'
# Filter environment variables containing "DATABASE"
docker inspect web-server | jq '.[0].Config.Env[] | select(contains("DATABASE"))'
Summary
docker inspect is the ultimate diagnostic utility in Docker’s CLI suite. By leveraging Go template formatting (--format) or piping to jq, you can instantly extract IP addresses, mount sources, runtime limits, and crash exit codes.
Takeaway: Save common Go template strings (like IP address and health status queries) as shell aliases to inspect container state instantly during live operations.