Inspect Docker Image Manifests Before You Pull

You will finish with a repeatable way to inspect an image in a registry, identify whether a reference is a single image or a multi-platform index, and record the digest and platform details before using it. The command only queries the registry. It does not start a container or alter the local image store.

Allow about ten minutes. You need Docker CLI access to a registry and a read-only image reference such as hello-world. The examples use Docker CLI 29.8.1 on this machine. The command is marked experimental by Docker, so check the installed help if your version differs. No example needs sudo.

1. Confirm the installed command

Check the client version and the exact syntax first. These are ordinary read-only commands:

$ docker version --format '{{.Client.Version}}'
29.8.1
$ docker manifest inspect --help
Usage:  docker manifest inspect [OPTIONS] [MANIFEST_LIST] MANIFEST

Display an image manifest, or manifest list

The installed command accepts one optional manifest-list name followed by the manifest reference. Its two useful options are --insecure, which permits communication with an insecure registry, and --verbose, which adds reference, digest and platform information.

2. Inspect a public image reference

Start with a tag that you can read without credentials. This fetches manifest metadata from the registry:

$ docker manifest inspect hello-world
{
   "schemaVersion": 2,
   "mediaType": "application/vnd.oci.image.index.v1+json",
   "manifests": [
      {
         "mediaType": "application/vnd.oci.image.manifest.v1+json",
         "digest": "sha256:...",
         "platform": {
            "architecture": "amd64",
            "os": "linux"
         }
      }
   ]
}

Your output will contain real sizes and digests, and the list may contain more platforms than the shortened example. A successful command prints JSON to standard output and exits successfully. Save the output when you need an audit record:

$ docker manifest inspect hello-world > hello-world.manifest.json
$ test -s hello-world.manifest.json && echo 'manifest saved'
manifest saved

Redirection creates or replaces the destination file in your current directory. Choose a new filename or make a backup first if an existing record matters. The inspection itself has not changed Docker state, but overwriting your only copy of a report is still avoidable.

3. Tell a single manifest from a multi-platform index

Look at the top-level mediaType. A value such as application/vnd.oci.image.index.v1+json or a Docker manifest-list media type means that the reference points to a collection of platform-specific manifests. Its manifests array shows each child digest and platform.

A single image normally has a top-level configuration object and a layers array instead. The layer entries include media types, sizes and content digests. These are descriptions of registry content, not a list of files you can edit locally.

For a compact platform-oriented view, use verbose output:

$ docker manifest inspect --verbose hello-world
{
   "Ref": "docker.io/library/hello-world:latest",
   "Digest": "sha256:...",
   "SchemaV2Manifest": { ... },
   "Platform": {
      "architecture": "amd64",
      "os": "linux"
   }
}

For an index, Docker can report the selected child manifest and its platform in verbose records. Exact field ordering and the number of records vary with the registry and image. Treat the digest as the stable identifier; a tag such as latest can be moved by its publisher.

4. Inspect a tag or digest deliberately

Image references may include a registry, repository, tag or digest. Make the choice explicit when reproducibility matters:

$ docker manifest inspect docker.io/library/hello-world:latest
$ docker manifest inspect docker.io/library/hello-world@sha256:REPLACE_WITH_A_REAL_DIGEST

Replace the second placeholder with a complete digest copied from trusted inspection output. Do not paste a shortened digest into a deployment file and assume it identifies one immutable image. A digest reference asks the registry for that exact content; a tag asks for whatever the registry currently associates with that name.

Inspection is not a signature or provenance verdict. A matching digest proves that the registry returned the referenced object, not that the publisher is trustworthy or that the image is safe. Use your organisation's signing, scanning and review policy before running an image.

5. Handle private and insecure registries

For a private registry, authenticate using your normal Docker credential process, then inspect the fully qualified reference:

$ docker login registry.example.test
$ docker manifest inspect registry.example.test/team/app:REPLACE_WITH_A_TAG

docker login changes Docker's credential configuration, so treat it as a security-sensitive step and follow your credential-store policy. Do not put passwords or access tokens in shell history, scripts or this article's command line.

Use --insecure only when the registry is intentionally configured for insecure transport or certificates that the client does not trust:

$ docker manifest inspect --insecure registry.example.test/team/app:REPLACE_WITH_A_TAG

This option permits the registry request to ignore some certificate and transport checks. It does not make the registry trustworthy. Prefer fixing the registry's TLS configuration and trust chain. If a normal request fails, first check the hostname, tag, credentials and certificate; adding --insecure should not be the automatic repair.

6. Diagnose the common failures

A non-zero exit status means the inspection did not complete. Capture the status immediately after the command:

$ docker manifest inspect docker.io/library/hello-world:missing-tag
$ status=$?
$ printf 'inspect status: %s\n' "$status"
inspect status: 1

The exact error text depends on the registry. A missing tag, denied repository, expired login, DNS problem or certificate failure all need different fixes. Check the reference and network access first, then authenticate if the repository is private. Do not infer that an image is absent merely because one credentialed request was denied.

If an image has several platform records, that is not itself an error. Compare the requested deployment platform with the available os, architecture and optional variant values. A manifest can exist while lacking a compatible platform for the host where you intend to run it.