docker inspect Command and How to Use It

The Docker daemon manages configurations, environment variables, and runtime states for containerized apps. Obtaining low-level metadata from resources helps to verify system configuration and diagnose errors.

This guide presents the docker inspect command, its structure, syntax, and use cases.

What Is docker inspect Command?

The docker inspect command is a diagnostic tool for extracting raw metadata from the Docker daemon. It exposes detailed JSON-formatted information about the system to help debug failures and automate infrastructure tasks.

The command queries the Docker daemon API and returns state and configuration details for host resources. It accepts names or unique identifiers of Docker images and containers, networks, volumes, plugins, and Docker Swarm nodes.

The output of the command is an array of JSON objects containing storage driver details, mount points, execution arguments, and state history.

docker inspect vs docker logs

The docker inspect command exposes metadata and current runtime states of Docker objects. docker logs displays stdout and stderr streams produced directly by the primary process inside a container.

The commands have different use cases:

• Use docker inspect when investigating system integration issues, port mappings, or missing volume mounts.
• Use docker logs when diagnosing application errors, database queries, or runtime stack traces.

How Does docker inspect Work?

When the user executes docker inspect, the command sends an HTTP GET request to the Docker daemon REST API endpoint. The daemon queries the local state database and returns a raw JSON array.

The Docker client receives the JSON payload and outputs it directly to standard output. Formatting flags instruct the client to filter and evaluate fields locally using built-in Go template rules.

docker inspect Syntax

Executing docker inspect requires specifying one or more target object names or IDs. Use command flags to modify output structure, filter targets by object, or view physical disk consumption.

The following is the basic command syntax:

docker inspect [options] [container_name_or_id]

If necessary, pass multiple container identifiers to instruct the CLI to query all specified objects and output them in a single JSON array:

docker inspect [options] [container1_name_or_id] [container2_name_or_id] […]

docker inspect Options

Command flags change the command scope and output formatting. The table below contains supported CLI flags for the docker inspect command:

Note: docker inspect is part of the Docker CLI set of commands. To learn more about Docker CLI, read Docker Commands Cheat Sheet.

docker inspect Examples

Use docker inspect to retrieve and filter relevant container information. The following examples show common use cases.

Obtain Container IP Address

Retrieve container IP addresses to enable direct communication testing between local services. To query the network IP directly, execute the following Go template syntax:

docker inspect --format='{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' [container_name_or_id]

Extract Mount Points and Bind Volumes

Check directory mappings to prevent misconfigured host paths. Use the command below to obtain the raw JSON array representing bound volumes and persistent storage mounts:

docker inspect --format='{{json .Mounts}}' [container_name_or_id]

Inspect Container Environment Variables

Containerized applications frequently read initialization parameters from environment key-value pairs. Inspect the full environment block assigned to an active container with the following command:

docker inspect --format='{{range .Config.Env}}{{println .}}{{end}}' [container_name_or_id]

Read Port Mappings

Mismatched host-to-container port assignments frequently cause network issues. Extract mapped host bindings across active container network ports by using the command below:

docker inspect --format='{{range $p, $conf := .NetworkSettings.Ports}}{{$p}} -> {{with $conf}}{{(index . 0).HostPort}}{{else}}none{{end}}{{println}}{{end}}' [container_name_or_id]

Check Container Restart Policy

If a host reboots or a process crashes, automated restart behaviors can influence application uptime. Extract the currently defined restart policy settings with the following command:

docker inspect --format='{{json .HostConfig.RestartPolicy}}' [container_name_or_id]

Retrieve Log File Paths on the Host System

By default, Docker stores standard output logs inside local host JSON file structures. Use the syntax below to retrieve the absolute host file system path to the container log file:

docker inspect --format='{{.LogPath}}' [container_name_or_id]

Filter Ambiguous Resource Names by Type

Resource name collisions can occur when a volume and container share identical labels. Use the --type flag to instruct Docker to look for containers:

docker inspect --type=container [container_name_or_id]

Read Total Container Storage Footprint

Standard docker inspect output does not show physical write layer storage metrics. Use the --size flag to show the relevant data:

docker inspect --size --format='Read-Write: {{.SizeRw}} bytes, Total: {{.SizeRootFs}} bytes' [container_name_or_id]

docker inspect Common Problems

Unexpected container terminations and networking errors generate metadata signatures in the docker inspect output. Identify an issue by inspecting specific JSON fields within the .State and .NetworkSettings hierarchies.

The following sections examine common problems and show how to extract diagnostic metadata.

Out of Memory (OOM) Exits (Exit Code 137)

The Linux kernel terminates processes immediately when memory consumption exceeds hard cgroup limits. Check whether the kernel Out-Of-Memory killer terminated the workload with the following command:

docker inspect --format='Status: {{.State.Status}} | ExitCode: {{.State.ExitCode}} | OOMKilled: {{.State.OOMKilled}}' [container_name_or_id]

An output showing ExitCode: 137 alongside OOMKilled: true confirms the container exceeded assigned memory allocations. If OOMKilled returns false despite exit code 137, an external system script or operator issued an explicit kill -9 signal.

Shell Command Not Found or Entrypoint Failures (Exit Code 127)

Misconfigured paths or missing dependencies can cause containers to exit immediately after creation. Use the command below to inspect the original command path and termination error:

docker inspect --format='ExitCode: {{.State.ExitCode}} | Error: {{.State.Error}} | Path: {{.Path}} | Args: {{json .Args}}' [container_name_or_id]

An exit code of 127 indicates that the Linux loader failed to locate the specified executable inside the container root file system.

Application Exception Crashing PID 1 (Exit Code 1)

Uncaught application exceptions can interrupt the primary workload process. The following command extracts termination timestamps and process status data:

docker inspect --format='ExitCode: {{.State.ExitCode}} | FinishedAt: {{.State.FinishedAt}} | Error: {{.State.Error}}' [container_name_or_id]

Exit code 1 signals an internal application failure. The failure can be caused by:

• A missing configuration file.
• Failed runtime dependency.
• Database connection timeout.

Container Trapped in Restart Loop

Aggressive restart policies mask startup crashes by constantly restarting the container. Check execution timestamps and process IDs to identify reboot loops:

docker inspect --format='RestartCount: {{.RestartCount}} | Status: {{.State.Status}} | PID: {{.State.Pid}}' [container_name_or_id]

High restart counts and rapidly changing process IDs confirm that the underlying binary fails continuously immediately after startup.

Unbound Network Ports and Binding Conflicts

Port mapping errors block outside connections from reaching internal services. Use docker inspect to check if ports have been mapped:

docker inspect --format='{{json .NetworkSettings.Ports}}' [container_name_or_id]

An empty output map ({}) indicates that the container exposes no ports to the external host interface.

Missing Network Connectivity or Subnet Isolation

If a container is assigned to an incompatible bridge network, the service is isolated. The command below checks current container network attach points and gateway targets:

docker inspect --format='{{range $net, $conf := .NetworkSettings.Networks}}Net: {{$net}} | IP: {{$conf.IPAddress}} | Gateway: {{$conf.Gateway}}{{println}}{{end}}' [container_name_or_id]

Empty network fields confirm that the container disconnected from active driver interfaces or failed to obtain an internal IP allocation.

Unmounted Storage Volumes and Path Mismatches

Containers outputting data to internal layers instead of persistent volume mounts may cause data loss. Inspect active volume destinations alongside host source paths using the syntax below:

docker inspect --format='{{range .Mounts}}Source: {{.Source}} -> Destination: {{.Destination}} (RW: {{.RW}}){{println}}{{end}}' [container_name_or_id]

An empty result set shows that the system created no bind mounts, sending all write operations directly to temporary container disk layers.

Conclusion

After reading this article, you know how to query, filter, and interpret low-level metadata from the Docker daemon. The guide showed how to extract container configurations and diagnose common container failure modes.

Next, read about the ways to fix the Invalid Reference Format error in Docker.