✦ For everyone, free.

Practical knowledge for real and everyday life

Home

19.2.6.1 Inspect Metadata Output

A focused guide to Inspect Metadata Output, connecting core concepts with practical Docker and container operations.

When you run docker inspect on a container, image, network, or volume, Docker returns a JSON array containing a single object (or multiple objects if multiple targets are specified) that holds all metadata associated with the inspected resource. This output is the raw, low-level data representation of the resource configuration and runtime state as stored by the Docker daemon.

Structure of the Output

The output is always a JSON array, even when inspecting a single resource:

docker inspect <container_name_or_id>

[
  {
    "Id": "a1b2c3d4e5f6...",
    "Created": "2024-03-15T10:22:00.000000000Z",
    "Path": "/bin/sh",
    "Args": ["-c", "nginx -g daemon off;"],
    "State": {},
    "Image": "sha256:abc123...",
    "NetworkSettings": {},
    "Mounts": [],
    "Config": {},
    "HostConfig": {}
  }
]

The top-level fields vary depending on whether you inspect a container, image, network, or volume.

Key Sections for Container Inspection

Id and Created

The Id field contains the full 64-character SHA256 identifier for the container. The Created field is an ISO 8601 timestamp indicating when the container was created (not started).

docker inspect --format "{{.Id}}" my_container
docker inspect --format "{{.Created}}" my_container
State

The State section reflects the current lifecycle state of the container:

"State": {
  "Status": "running",
  "Running": true,
  "Paused": false,
  "Restarting": false,
  "OOMKilled": false,
  "Dead": false,
  "Pid": 1842,
  "ExitCode": 0,
  "Error": "",
  "StartedAt": "2024-03-15T10:22:05.000000000Z",
  "FinishedAt": "0001-01-01T00:00:00Z"
}
  • Status: One of created, running, paused, restarting, removing, exited, or dead.
  • Pid: Host process ID of the container main process.
  • OOMKilled: Set to true if the container was terminated due to an out-of-memory condition.
  • ExitCode: Exit code of the main process if the container has stopped.
Config

The Config section captures the container configuration as set at creation time, derived from the image and any overrides:

"Config": {
  "Hostname": "a1b2c3d4e5f6",
  "Domainname": "",
  "User": "",
  "ExposedPorts": {
    "80/tcp": {}
  },
  "Env": [
    "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
    "NGINX_VERSION=1.25.3"
  ],
  "Cmd": ["nginx", "-g", "daemon off;"],
  "Image": "nginx:latest",
  "WorkingDir": "/etc/nginx",
  "Labels": {
    "maintainer": "team@example.com"
  }
}
  • Env: Full list of environment variables injected into the container.
  • ExposedPorts: Ports declared by the image or at container creation, not necessarily published to the host.
  • Labels: Key-value metadata attached to the container.
HostConfig

The HostConfig section describes how the container is bound to the host machine, including resource constraints and port bindings:

"HostConfig": {
  "Binds": ["/host/data:/container/data:rw"],
  "PortBindings": {
    "80/tcp": [{ "HostIp": "", "HostPort": "8080" }]
  },
  "RestartPolicy": {
    "Name": "unless-stopped",
    "MaximumRetryCount": 0
  },
  "Memory": 536870912,
  "NanoCpus": 500000000,
  "NetworkMode": "bridge",
  "Privileged": false,
  "ReadonlyRootfs": false
}
  • Binds: Volume mounts from host directories or named volumes.
  • PortBindings: Maps container ports to host ports.
  • Memory: Memory limit in bytes (0 means no limit).
  • NanoCpus: CPU quota in nanoseconds (500000000 equals 0.5 CPUs).
  • RestartPolicy: Defines when Docker automatically restarts the container.
NetworkSettings

The NetworkSettings section provides full networking metadata, including assigned IP addresses, MAC addresses, and which networks the container belongs to:

"NetworkSettings": {
  "IPAddress": "172.17.0.2",
  "IPPrefixLen": 16,
  "Gateway": "172.17.0.1",
  "MacAddress": "02:42:ac:11:00:02",
  "Ports": {
    "80/tcp": [{ "HostIp": "0.0.0.0", "HostPort": "8080" }]
  },
  "Networks": {
    "bridge": {
      "NetworkID": "d1e2f3...",
      "EndpointID": "a4b5c6...",
      "Gateway": "172.17.0.1",
      "IPAddress": "172.17.0.2",
      "IPPrefixLen": 16,
      "MacAddress": "02:42:ac:11:00:02"
    }
  }
}
  • Ports: Shows which container ports are published and to which host ports.
  • Networks: Lists all networks the container is connected to, with individual IP assignments per network.
Mounts

The Mounts section lists all filesystem mounts active in the container:

"Mounts": [
  {
    "Type": "bind",
    "Source": "/host/data",
    "Destination": "/container/data",
    "Mode": "rw",
    "RW": true,
    "Propagation": "rprivate"
  },
  {
    "Type": "volume",
    "Name": "my_volume",
    "Source": "/var/lib/docker/volumes/my_volume/_data",
    "Destination": "/app/storage",
    "Driver": "local",
    "RW": true
  }
]
  • Type: Either bind, volume, or tmpfs.
  • Source: Path on the host filesystem.
  • Destination: Path inside the container.
  • RW: Boolean indicating whether the mount is read-write.

Extracting Specific Fields with --format

Instead of parsing the full JSON, you can use the --format flag with Go template syntax to extract specific fields:

docker inspect --format "{{.State.Status}}" my_container
docker inspect --format "{{.NetworkSettings.IPAddress}}" my_container
docker inspect --format "{{.HostConfig.Memory}}" my_container

The --format option is particularly useful in scripts where you need a single value without parsing JSON manually.

Inspecting Multiple Resources at Once

You can pass multiple identifiers to docker inspect in a single command:

docker inspect container_a container_b
docker inspect my_network my_volume

The output will be a JSON array with one element per resource.

Differences When Inspecting Images

When you inspect an image rather than a container, the output includes fields like RootFS, Layers, Architecture, and Os instead of runtime state fields:

docker inspect nginx:latest

[
  {
    "Id": "sha256:abc123...",
    "RepoTags": ["nginx:latest"],
    "Created": "2024-03-01T00:00:00Z",
    "Architecture": "amd64",
    "Os": "linux",
    "Size": 187456789,
    "RootFS": {
      "Type": "layers",
      "Layers": [
        "sha256:layer1...",
        "sha256:layer2...",
        "sha256:layer3..."
      ]
    }
  }
]

Practical Use Cases

Checking whether a container is healthy:

docker inspect --format "{{.State.Health.Status}}" my_container

Getting the full environment variable list:

docker inspect --format "{{range .Config.Env}}{{println .}}{{end}}" my_container

Exporting inspect output to a file for audit purposes:

docker inspect my_container > container_metadata.json

The metadata output from docker inspect is the authoritative source of truth for a resource configuration as understood by the Docker daemon. It reflects what was applied at creation time combined with any runtime changes, making it essential for debugging, auditing, and automation tasks.

Related content