Inspect Docker Images Without Guessing at Their Metadata

You will finish with a repeatable way to check which Docker image you have, identify its platform, and extract the few fields you actually need. The examples use Docker CLI 29.8.1 from package docker-ce-cli 5:29.8.1-1~ubuntu.24.04~noble, with the local alpine image. Allow about ten minutes. You need a shell, a working Docker daemon, and an image name or ID that is already available locally or can be resolved by Docker.

docker image inspect reads image metadata. It does not start a container, change an image, or require root when your account already has access to the Docker socket. Membership of the docker group is effectively privileged access to the daemon, so do not add users to that group just to make this command convenient.

1. Confirm the command and the image

Check the installed command before relying on a copied example. This is a read-only command and normally needs no elevated privileges:

$ docker --version
Docker version 29.8.1, build 4a63305
$ docker image inspect --help

The syntax is docker image inspect [OPTIONS] IMAGE [IMAGE...]. The final argument is an image reference, such as alpine:latest, a repository digest, or an image ID. Tags are mutable names, so use a digest or a full ID when you need an auditable result.

Checkpoint: verify that the reference resolves before building a longer command:

$ docker image inspect alpine --format '{{.Id}}'
sha256:294b683cb724975bec92580e1e685676bd4b50dba910ddb8c51d4cabeaec77e6

Your ID will differ if the local image has changed. If Docker says that the image is not found, check the spelling and tag. Inspecting an image reference can cause Docker to contact a registry when another command has pulled it first, but this command does not itself modify the image.

2. Read the complete metadata once

Run the command without --format when you need context. The result is JSON-like output containing fields such as the ID, tags, digests, creation time, configuration, architecture, operating system and layer information:

$ docker image inspect alpine
[
    {
        "Id": "sha256:294b683cb724...",
        "RepoTags": [
            "alpine:3",
            "alpine:latest"
        ],
        "Architecture": "amd64",
        "Os": "linux",
        "Config": {
            "Cmd": [
                "/bin/sh"
            ]
        }
    }
]

The abbreviated ID above is for readability. Do not parse this display with line-oriented tools: nested arrays and objects make that brittle, and the exact field set varies with the image and Docker version. Use a format template for a value that another command or check will consume.

3. Extract identity and platform fields

The -f and --format options accept a Go template. Keep the template in single quotes so the shell passes its braces and dots unchanged:

$ docker image inspect --format '{{.Id}} {{.Os}}/{{.Architecture}}' alpine
sha256:294b683cb724975bec92580e1e685676bd4b50dba910ddb8c51d4cabeaec77e6 linux/amd64
$ docker image inspect --format '{{json .RepoTags}}' alpine
["alpine:3","alpine:latest"]

These examples use fields observed in the installed image. A missing field may render as an empty value, and a field can have a different shape from what you expect. Test a template against one known image before putting it in a script.

For a machine-readable result, use Docker's special json format:

$ docker image inspect --format json alpine

That output is suitable for a JSON parser. It is safer than trying to extract values from the default multi-line display, particularly when you inspect several images.

4. Inspect more than one image deliberately

The command accepts one or more image arguments. Docker returns one metadata object per reference, in command order:

$ docker image inspect alpine:3 alpine:latest --format '{{.RepoTags}} {{.Id}}'
[alpine:3 alpine:latest] sha256:294b683cb724975bec92580e1e685676bd4b50dba910ddb8c51d4cabeaec77e6
[alpine:3 alpine:latest] sha256:294b683cb724975bec92580e1e685676bd4b50dba910ddb8c51d4cabeaec77e6

The exact values depend on the local cache. When tags point to the same image, the IDs may match. Treat a tag match as useful evidence, not as a permanent guarantee: a later pull can move a tag to a different ID.

For a script, fail on an unresolved reference and check the status immediately:

$ if ! docker image inspect 'IMAGE_REFERENCE' >/dev/null; then
>     printf 'image not available: %s\n' 'IMAGE_REFERENCE' >&2
>     exit 1
> fi
$ printf 'image metadata is available\n'
image metadata is available

Replace IMAGE_REFERENCE with a value you control. Quote it if it comes from a variable. Do not pass arbitrary user input as a sequence of extra Docker options.

5. Check a multi-platform image

The installed command supports --platform for inspecting a specific platform of a multi-platform image. Use an explicit value such as linux/amd64 when the platform matters:

$ docker image inspect --platform linux/amd64 --format '{{.Os}}/{{.Architecture}}' alpine
linux/amd64

The platform is written as os[/arch[/variant]]. Docker reports an error if the image or server cannot handle the requested platform, or if it does not match. That is useful evidence: do not silently remove --platform just to make a failing check pass.

A platform check is not the same as proving that an application will run correctly. It identifies the image variant Docker selected. Runtime behaviour can still depend on the host kernel, mounts, capabilities and application configuration.

6. Diagnose the common failures

A daemon connection error means the CLI could not reach Docker. Check the service and socket according to your distribution, then rerun the harmless metadata command. Do not begin by using sudo: that can change which Docker configuration and socket the CLI uses, and it can hide a permissions problem.

An image-not-found error usually means the reference is wrong or the image is not present. Confirm the complete repository and tag. If pulling is appropriate, treat that as a separate state-changing operation and verify the image digest afterwards. This guide does not pull, delete or retag anything.

A template error or empty value is a data-shape problem. Start with the full inspection, confirm the field name and then add one expression at a time. Keep the original image reference and expected ID in your logs when the result is part of a deployment check.