Skip to content
Blog

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.

Sources