Read Any Docker Object's State with docker inspect

When you need the full truth about a container or image and a one-line status will not cut it, docker inspect is where you go. You will use it to read the detailed metadata for a container or image, extract one useful value with a Go template, and handle name collisions without inspecting the wrong object. The examples match Docker CE CLI 29.8.1, installed from docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble.

1. Choose an object you can inspect

The command accepts one or more object names or IDs:

$ docker inspect NAME|ID [NAME|ID...]

A container name, a container ID, an image name such as repository/name:tag, and several other Docker object types can all be targets. Start with a name or ID that already exists. This read-only listing helps you choose an exact container without changing anything:

$ docker ps -a --format 'table {{.ID}}\t{{.Names}}\t{{.Image}}'
CONTAINER ID   NAMES    IMAGE
2626d6c28708   parish   parish:latest

Your rows will differ. Replace CONTAINER_NAME below with an exact name from your own output. The short ID is also accepted, but a name is usually easier to recognise in a script or incident note.

Checkpoint: confirm that the target resolves before adding a template:

$ docker inspect CONTAINER_NAME >/tmp/docker-inspect.json
$ test -s /tmp/docker-inspect.json && echo 'inspection written'
inspection written

The default output is a JSON array, even when you inspect one object. The temporary file is only a convenient way to review a large result; remove it afterwards if it contains information you do not want to retain.

2. Read the full result safely

For a quick terminal review, send the result through a pager:

$ docker inspect CONTAINER_NAME | less

The exact fields depend on the object and Docker version. Do not assume a field is present just because it appeared in another container.

Warning: inspection can expose environment variables, bind-mounted paths, command arguments, network addresses and logging paths. Treat its output as sensitive operational data. Avoid pasting an unfiltered result into a public issue, and prefer a narrow template when you only need one field.

3. Resolve an ambiguous name with --type

Docker can have objects of different types sharing the same name. Without a type restriction, an ambiguous name may not identify what you intended. Select the type explicitly:

$ docker inspect --type=container CONTAINER_NAME
$ docker inspect --type=image IMAGE_NAME
$ docker inspect --type=volume VOLUME_NAME
$ docker inspect --type=network NETWORK_NAME

The installed command documents container, image, volume, network, node, service and task objects, among others. Use the type that matches the object you are investigating. This matters most in scripts, where silently selecting an unexpected object can produce a plausible but wrong answer.

Checkpoint: make the type part of the command before saving an inspection result:

$ docker inspect --type=container CONTAINER_NAME --format '{{.Name}}'
/parish

The leading slash in a container's .Name is normal. A non-zero error means the supplied name or type did not resolve; it does not mean Docker has changed the object.

4. Extract one field with --format

Use -f or --format when JSON is more detail than your next command needs. In a POSIX shell, single quotes preserve the template braces and dollar signs:

$ docker inspect --type=container CONTAINER_NAME --format '{{.Config.Image}}'
parish:latest

Other practical fields include the configured command and the log path:

$ docker inspect --type=container CONTAINER_NAME --format '{{json .Config.Cmd}}'
null
$ docker inspect --type=container CONTAINER_NAME --format '{{.LogPath}}'
/var/lib/docker/containers/.../...-json.log

The exact values are host-specific. json is useful for a field that is itself an array or object, because it keeps the result valid JSON rather than printing a Go-style value. Quote the template as shown: an unquoted template is easy for the shell to mangle, and a double-quoted one makes shell expansion more likely when the template contains a dollar sign.

5. Query network and port data carefully

Network information is nested and can contain more than one network. To print every assigned container IP, iterate over the networks:

$ docker inspect --type=container CONTAINER_NAME --format '{{range .NetworkSettings.Networks}}{{println .IPAddress}}{{end}}'
<one address per line, when assigned>

An empty result can be valid for a stopped container or an object without an address. The value is host-specific, and this command can also report a daemon-side network error. Do not turn an empty or invalid value into a guessed IP address. For all published port mappings, iterate over the ports map:

$ docker inspect --type=container CONTAINER_NAME --format '{{range $port, $bindings := .NetworkSettings.Ports}}{{$port}} -> {{with $bindings}}{{(index . 0).HostPort}}{{else}}not published{{end}}{{println}}{{end}}'
<port/protocol> -> <host port>

A port can be exposed without being published on the host, which is why the template handles an empty binding list. If you need a particular numeric port, use index with its complete key such as 8787/tcp: field notation does not work for keys that begin with a number.

6. Add container size information only when needed

The -s or --size option adds SizeRootFs and SizeRw for a container:

$ docker inspect --type=container --size CONTAINER_NAME --format '{{.SizeRootFs}} bytes total, {{.SizeRw}} bytes changed'
123456789 bytes total, 8192 bytes changed

The numbers above are illustrative: use your command's own output as the measurement. SizeRootFs is the total container file-system size in bytes, while SizeRw is the size of files created or changed compared with the image. The option applies to containers, including stopped ones, and is not a general image-size switch.

Do not read SizeRw as a complete disk-usage report for every volume or host path. Mounted data lives outside the container's writable layer and needs measuring at its actual source.

Common traps

Done means