Inspect Docker Containers Without Guessing Their State

docker container inspect turns a container's hidden state into a JSON record you can actually read. You will finish with a repeatable way to select a few useful fields for scripts and save a complete inspection when you need to investigate a problem. The examples match Docker CLI 29.8.1 from the installed docker-ce-cli package, version 5:29.8.1-1~ubuntu.24.04~noble.

Allow about ten minutes. You need a shell, the Docker CLI, access to a Docker daemon, and the name or ID of a container. This guide only reads metadata. It does not start, stop, remove or otherwise change a container. Most commands are unprivileged, although access to a local Docker socket may be granted through a group or require a carefully considered sudo.

1. Check the installed command

Confirm which CLI will run and inspect its local option contract:

$ command -v docker
/usr/bin/docker
$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker container inspect --help
Usage:  docker container inspect [OPTIONS] CONTAINER [CONTAINER...]

Display detailed information on one or more containers

The command accepts one or more container names or IDs. The relevant options in this installed version are --format, also written -f, and --size, also written -s. An ordinary help check does not contact the daemon.

Checkpoint: If command -v docker points at an unexpected installation, stop and fix your shell's PATH before comparing output with this guide.

2. Choose a container without changing it

List containers so you can copy an exact name or ID. This is still read-only:

$ docker container ls --all
CONTAINER ID   IMAGE          COMMAND       CREATED        STATUS          NAMES
abc123def456   example:tag   "..."         2 hours ago    Up 2 hours      example-app

The values in this table are illustrative. Your host will show different containers, images and times. Use the value from your own NAMES or CONTAINER ID column. If the list is empty, there is no local container to inspect; do not substitute an image name because an image and a container are different objects.

Set a shell variable after checking the value. Quoting it keeps whitespace or shell metacharacters from changing the command:

$ CONTAINER_NAME='example-app'
$ docker container inspect "$CONTAINER_NAME" > /tmp/example-app.inspect.json
$ test -s /tmp/example-app.inspect.json && echo 'inspection saved'
inspection saved

The file is JSON, usually returned as an array even when you inspect one container. It can contain credentials or other sensitive configuration, so protect it like operational data. Remove this temporary copy after use with rm -- /tmp/example-app.inspect.json; that deletion cannot be undone.

3. Read the complete inspection

Print the full record when you need context, such as mount definitions, environment entries, restart policy, image identity, process state or network settings:

$ docker container inspect "$CONTAINER_NAME"
[
    {
        "Id": "...",
        "Created": "...",
        "State": {
            "Status": "running",
            "Running": true
        },
        "Config": {
            "Image": "example:tag"
        }
    }
]

Docker returns far more fields than the shortened display above. Do not rely on the order of fields or on whitespace. For automation, select named fields with a template or parse the JSON with a JSON-aware tool. Avoid pasting the full output into tickets or chat without checking for secrets in environment variables, labels and command arguments.

A successful inspection proves that Docker found the object and returned its record. It does not prove that the application inside is healthy or accepting traffic. Use the container's health field, logs, an application check or a service-specific probe for that separate question.

4. Select stable fields with a Go template

Use --format when a human or script needs a small answer. The template is evaluated against each inspected container:

$ docker container inspect \
    --format '{{.Name}} status={{.State.Status}} image={{.Config.Image}} exit={{.State.ExitCode}}' \
    "$CONTAINER_NAME"
/example-app status=running image=example:tag exit=0

Names commonly begin with a slash in this output. The image, status and exit code are examples, not promises about your container. A stopped container can still have a useful image and an exit code from its last process. A running container's exit code is commonly zero, but the status is the more relevant field while it is running.

For a compact machine-readable answer, ask for JSON:

$ docker container inspect \
    --format '{{json .State}}' \
    "$CONTAINER_NAME"
{"Status":"running","Running":true,"Paused":false,"Restarting":false,"OOMKilled":false,"Dead":false,"Pid":1234,"ExitCode":0}

Process IDs, timestamps and the remaining state values depend on the container. Treat this as a sample shape, not fixed output. If you need a script to consume it, pass the result to a JSON parser rather than matching spaces or line breaks.

5. Inspect more than one container

Pass multiple names or IDs as separate arguments. Docker emits one result for each object, in the order it processes them:

$ docker container inspect \
    --format '{{.Name}} {{.State.Status}}' \
    frontend backend
/frontend running
/backend exited

Keep each name as its own quoted shell argument when values come from another command. A missing or misspelled container causes a non-zero result, so check the exit status in a script:

$ docker container inspect "$CONTAINER_NAME" > /tmp/inspect.json
$ inspect_status=$?
$ printf 'inspect exit status: %s\n' "$inspect_status"
inspect exit status: 0

Do not treat an empty template result as proof that a field is absent unless you have checked the object and template spelling. Go template field names are case-sensitive and nested fields may be unavailable for a particular object.

6. Include container size when storage matters

Add --size when you need Docker's size information:

$ docker container inspect --size \
    --format '{{.Name}} rw={{.SizeRw}} rootfs={{.SizeRootFs}}' \
    "$CONTAINER_NAME"
/example-app rw=4096 rootfs=123456789

The exact values depend on the writable layer and image. Size reporting can take longer on a container with substantial filesystem data, and it is not a replacement for checking host filesystem capacity. Do not use it as a destructive cleanup command: inspect never removes files or layers.

7. Diagnose the likely failures

If Docker says it cannot connect to the daemon, check the daemon's availability and the context you selected before changing permissions:

$ docker context show
default
$ docker info

docker info may report a socket, service or permission problem. A permission error is not a reason to make the Docker socket world-readable. Adding a user to the Docker group grants powerful control over the host; obtain the required administrative approval, make the smallest change appropriate for the system, and start a new login session before retesting. sudo docker ... also grants root-equivalent authority and should be an explicit operational decision.

If the command says that a container is not found, rerun docker container ls --all in the same Docker context. A container name from another host, project or context is not local evidence. If a template prints nothing, first run the unformatted inspection and compare the field path with the returned structure.

Done means