Overview
This document explains the difference in download count behaviour between list.manifest.json and manifest.json.When pulling multi-architecture Docker images from JFrog Artifactory. The described behaviour is expected and aligns with the functionality of the Docker client and Artifactory’s checksum-based storage mechanism.
Multi-Architecture Image Structure
A multi-architecture Docker image contains multiple architecture-specific variants within a single image reference. The top-level object is the manifest list (list.manifest.json), also known as an OCI Image Index. This file references multiple platform-specific manifests, such as amd64 or arm64. Each referenced object is an architecture-specific manifest.json, which in turn references the image configuration and the associated layer blobs. Each manifest is uniquely identified by its SHA digest.
Docker Pull Behaviour
When a Docker image is pulled using a tag (for example, docker pull <image>:<tag>), the Docker client first retrieves the manifest list to resolve the tag to its current digest. This request is mandatory for every tag-based pull operation because Docker must confirm that the tag still points to the expected image version. As a result, Artifactory consistently registers a download for list.manifest.json with every pull attempt.
After retrieving the manifest list, Docker selects the appropriate architecture-specific manifest.json based on the client’s platform. Before downloading this manifest, Docker verifies whether the manifest digest already exists in its local storage. Docker uses content-addressable storage and identifies artifacts by their SHA values. If the manifest digest and its associated layers are already present locally, Docker may skip the GET request entirely or perform only a HEAD request for validation. In such cases, Artifactory does not record a download for manifest.json, since no full artifact retrieval occurs.
Artifactory Storage Model
JFrog Artifactory uses checksum-based storage, ensuring that identical blobs are stored only once, even if referenced by multiple images. Download counts are incremented only when a full GET request for an artifact occurs. Because the list.manifest must always be retrieved for tag resolution; its download count increases consistently. In contrast, the architecture-specific manifest is downloaded only when its digest is not already available locally, which explains why its download count may remain zero or increase only under certain conditions.
Impact of Cleanup Operations
Running docker system prune --all --volumes --force removes unused images, containers, and volumes internally, freeing logical space. However, this operation does not necessarily remove all cached digests or shrink the physical size of the Docker.raw file.
Because Docker continues to recognise existing manifest digests within its storage, the architecture-specific manifest.json may not be downloaded again, while the manifest list continues to increment with each pull.
Only when Docker storage is fully cleared, such as through a Docker Desktop data purge or a factory reset, is the Docker.raw file removed or recreated. In that scenario, Docker must re-download the manifest list, the architecture-specific manifest, and all image layers. At that point, Artifactory records download counts for both list.manifest.json and manifest.json.
Behaviour Across Different Images and Shared Digests
Different images may share identical base layers or even identical architecture-specific manifest digests. If a previously pulled image references the same digest, Docker will not re-download the manifest.json for a new image that uses the same content. This behaviour explains variations observed between different images, where the manifest list consistently increments while the architecture-specific manifest may not.
The manifest.json download count typically increases only when the pull is executed from a new environment or a different client that does not already have the manifest digest cached. For example, using a different server, a fresh Docker installation, or alternative container tools such as Podman or ORAS results in a full GET request for the manifest because the local content store does not contain the required digest. Since Artifactory increments download counts only when a full GET request is performed, the increase in manifest.json downloads directly depends on whether the client determines that it must retrieve the manifest from the registry rather than reuse a locally cached copy.
Conclusion
The higher download count for list.manifest.json compared to manifest.json is a direct and expected result of Docker’s tag resolution process, content-addressable storage model, and local digest verification mechanism. Docker always retrieves the manifest list when pulling by tag, but it downloads the architecture-specific manifest only if its digest is not already available locally. This behaviour confirms the expected interaction between the Docker client and Artifactory.