Before looking at the file format itself, it helps to understand the layered structure a container registry actually stores, and where a manifest list fits within it.

The layered structure a registry actually stores

A container registry does not store one flat “image” object per name and tag. It stores several distinct layers of metadata: individual filesystem layers (the actual compressed data that makes up an image’s content), a manifest describing which layers make up one specific image for one specific platform, and — when an image supports more than one platform — a manifest list sitting above all of those individual manifests, tying them together under one shared, human-facing name and tag. A manifest list contains no actual application code or filesystem content of its own; it is pure metadata, a table of contents pointing at the real, platform-specific manifests underneath it.

Why “multi-arch” is really just “multi-manifest, one list”

A common misconception is imagining a multi-architecture image as a single, unusual file that somehow contains code for several CPU architectures at once. In reality, each platform gets its own completely ordinary, single-platform image, built and stored exactly as any other image would be. The only thing that makes it “multi-arch” from the outside is the manifest list sitting above those ordinary images, listing each one alongside the specific platform it was built for. Nothing about an individual platform-specific image inside that list is special or different from an image published without any manifest list at all.

What a manifest list actually records for each platform

For every platform-specific image it references, a manifest list records, at minimum, that image’s own manifest digest (a cryptographic fingerprint uniquely identifying its exact content), along with platform-descriptor fields specifying the target CPU architecture, the target operating system, and, where relevant, additional qualifiers like a specific CPU variant. This is the exact information a container runtime needs in order to correctly match its own host’s platform against the available entries in the list.

A closer look at the specific pieces that make up a manifest list, and the tooling that creates and consumes it.

flowchart TB
    TAG["myapp:latest
(shared name and tag)"]
    ML["Manifest List / Image Index"]
    M1["Manifest A
platform: linux/amd64"]
    M2["Manifest B
platform: linux/arm64"]
    M3["Manifest C
platform: linux/arm/v7"]
    L1["Layers + Config (amd64 image)"]
    L2["Layers + Config (arm64 image)"]
    L3["Layers + Config (armv7 image)"]

    TAG --> ML
    ML --> M1 --> L1
    ML --> M2 --> L2
    ML --> M3 --> L3
    

Where the manifest list sits in the pull request flow

When a client requests an image by name and tag, the registry’s response depends entirely on what was actually pushed under that reference: if a single-platform manifest was pushed, the registry returns that manifest directly; if a manifest list was pushed, the registry returns the list itself, and it becomes the client’s job to inspect that list, select the matching platform entry, and issue a second request for that specific manifest. This two-step resolution — list first, then the matching manifest — is precisely what allows one name to transparently serve many different platforms.

A detailed walk through exactly what happens, request by request, from the moment a pull command is issued to the moment the correct image lands on disk.

Step one: resolving the tag to content

When a pull is initiated, the client’s first request to the registry asks for whatever object is currently associated with the given name and tag. The registry responds with that object’s content type identified in the response — either an ordinary single-platform manifest, or a manifest list — along with the object’s own content. If it is a manifest list, the client now has, in hand, the complete set of platform options available under that tag, without having downloaded any actual application layers yet.

Step two: platform matching

With the manifest list in hand, the client compares its own host’s detected operating system and CPU architecture (and, where relevant, more specific qualifiers like a CPU variant) against each entry’s platform descriptor, looking for an exact or sufficiently compatible match. This comparison happens entirely client-side, using platform information the client already knows about its own host — the registry itself does not need to know anything about which specific machine is asking, since all the necessary platform options were already delivered in the manifest list response.

sequenceDiagram
    participant C as Client (Docker CLI)
    participant R as Registry

    C->>R: GET manifest for myapp:latest
    R-->>C: manifest list (all platform entries)
    C->>C: detect local platform (e.g. linux/arm64)
    C->>C: find matching entry in list
    C->>R: GET manifest by digest (matched entry)
    R-->>C: platform-specific manifest
    C->>R: GET layer blobs by digest
    R-->>C: layers (native arm64 content)
    C->>C: assemble and run container natively
    

Step three: fetching only the matched content

Once the correct platform-specific manifest has been identified, the client issues a further request for that specific manifest by its digest, then downloads only the layer blobs referenced by that one manifest — never the layers belonging to any of the other, unmatched platform entries in the list. This is an important efficiency property worth being explicit about: pulling a multi-architecture image does not mean downloading every platform’s content and discarding what isn’t needed; only the genuinely relevant, matched platform’s data ever crosses the network to that particular host.

Digest immutability as the trust mechanism

Every reference inside a manifest list — from the list to each platform manifest, and from each manifest to its layers — is by content digest, a cryptographic hash of the referenced object’s exact bytes. This means a manifest list cannot silently or accidentally point to different content than what was originally published without that change being immediately, mathematically detectable, since even a single-byte difference in the referenced content produces a completely different digest.

Following a multi-architecture image from an initial build through to eventual consumption across a fleet of mixed-platform hosts.

What happens when a host’s platform has no matching entry

If a client’s detected platform does not correspond to any entry in the manifest list — for example, a host running an architecture the image was simply never built for — the pull fails with a clear “no matching manifest” style error, rather than silently falling back to an incompatible platform’s content or attempting any kind of automatic emulation on the client’s own initiative. This explicit failure is intentional: silently running the wrong platform’s binary would be far more dangerous than a clear, immediate failure that tells the operator exactly what platform support is missing.

Manifest lists solve a genuine problem elegantly, but adopting them fully is not entirely without cost.

The trade-off between one tag and platform-suffixed tags

Before manifest lists became standard, a common workaround for multi-platform distribution was publishing separate, platform-suffixed tags — one name for the x86-64 build, a differently named tag for the ARM build — and leaving it to the person deploying the image to manually select the correct one for their own hardware. Manifest lists remove that manual burden entirely, at the cost of an extra layer of indirection that makes “what am I actually running” a slightly less immediately obvious question than it was when the platform was spelled out directly in the tag name itself. For nearly all modern use cases, the convenience and correctness gained from automatic platform resolution outweighs that small loss of at-a-glance clarity, particularly since the underlying platform-specific manifest can still always be inspected explicitly when needed.

Manifest lists interact with image supply chain security in specific, important ways, both strengthening and complicating parts of the trust picture.

Digest pinning as a supply-chain defense

Because every reference inside a manifest list is a cryptographic digest rather than a mutable name, pinning a deployment to a specific manifest list digest — rather than a floating tag like “latest” — provides a strong, verifiable guarantee that the exact same content, across every referenced platform, will be pulled every single time, immune to the tag being silently repointed at different content later. This makes manifest list digests a genuinely valuable tool for supply-chain-conscious deployments that want reproducible, auditable image references rather than a mutable name that could theoretically resolve to different content at different times.

Ensuring every referenced platform is equally trustworthy

A manifest list is only as secure as its least-scrutinized entry: if an organization’s security scanning and signing process is rigorously applied to one platform’s build but only loosely applied to another platform included in the same manifest list, the overall image carries a real, if easy-to-overlook, inconsistency in its security posture depending purely on which platform a given host happens to pull. Comprehensive image security practices — vulnerability scanning, signing, provenance attestation — need to be applied uniformly across every platform entry in a manifest list, not just the platform a security team happens to test most often.

Verifying that a manifest list genuinely covers what it should, and diagnosing pull-time platform-matching failures, requires inspecting the right layer of metadata.

Confirming a manifest list’s actual platform coverage

The most fundamental verification step for any published multi-architecture image is directly inspecting its manifest list to confirm every intended platform is genuinely present with a valid, resolvable digest, rather than assuming coverage based purely on the build pipeline’s reported success. A build step that appears to succeed can still, due to a misconfiguration, omit a platform from the final published list, and this class of gap is only reliably caught by explicitly checking the published list’s actual contents, not by trusting the build log alone.

Diagnosing a “no matching manifest” pull failure

When a pull fails with an error indicating no compatible manifest was found, the most productive first step is inspecting the manifest list’s actual platform entries directly and comparing them against the pulling host’s own detected platform string, since the mismatch is very often a narrower, more specific gap than it first appears — a missing CPU variant qualifier, for instance, rather than an entirely absent architecture. Treating this class of error as purely “the image doesn’t support my platform” without checking the exact entries can obscure a much smaller, more easily fixed gap in the published list.

Recurring, well-established approaches for managing manifest lists at scale, alongside the mistakes that quietly erode their benefits.

Concrete guidance for publishing and consuming manifest lists reliably, across teams and over time.

Manifest lists are the invisible mechanism behind an enormous share of everyday container image pulls across the industry.

A manifest list is a small, elegant piece of indirection that quietly does an enormous amount of work behind every modern multi-platform Docker image pull.