In a container registry, what is the difference between referencing an image by tag (for example myapp:1.4) and referencing it by its sha256 digest (myapp@sha256:ab12...)?

## Two different kinds of name A container image reference has three parts: a registry host, a repository path, and a *selector*. The selector is either a **tag** (`:1.4`) or a **digest** (`@sha256:ab12…`). They look similar in a command line but they are fundamentally different kinds of name. A **tag** is a mutable key in a mutable map. The registry keeps, per repository, a table from tag name to manifest digest. `docker push myapp:1.4` writes an entry in that table. Pushing again with the same tag overwrites the entry — the old manifest usually still exists (it is still addressable by its digest) but nothing named points at it any more. Nothing in the protocol prevents this; the registry API explicitly supports repointing tags. So a tag answers the question "what does this name mean *right now*?", and the answer can change between two pulls a minute apart. A **digest** is a content address. When you build an image, the registry stores a JSON **manifest** that lists the digest of the config blob and the digest of every layer blob. The image digest is `sha256` over the exact bytes of that manifest. Change any layer, any environment variable in the config, any label — the config blob changes, so the manifest changes, so the digest changes. Two references with the same digest are, byte for byte, the same image. There is no way to "push different content to a digest", because the digest is derived from the content. ## Why this matters operationally 1. **Reproducibility.** `FROM node:20-alpine` in a Dockerfile built in January and rebuilt in June can produce two different base layers. `FROM node:20-alpine@sha256:…` cannot. 2. **Integrity.** A client that pulls by digest verifies the hash of what it received. Pulling by tag verifies the layers against the manifest the registry handed you, but you have no independent statement about *which* manifest you should have gotten. Digest pinning is the base layer that image signing builds on. 3. **Debuggability.** "Which image is running in prod?" has one true answer only if you record a digest. Tag answers rot. 4. **Caching semantics.** Because a digest is immutable, a node that already has that digest never needs to re-check the registry. A tag always needs a round trip to see whether it moved. ## Finding the digest Locally, after a push or pull, `docker images --digests` shows the **repo digest** — the digest under which that image is known in that registry. It is empty for images that were only built locally and never pushed, because the digest is a property of the pushed manifest, not of the local build. `docker inspect --format '{{index .RepoDigests 0}}' myapp:1.4` extracts it. `docker buildx imagetools inspect myapp:1.4` queries the registry directly without pulling. Beware a common confusion: `docker images` also shows an **IMAGE ID**, which is the digest of the *local image config*, not the registry manifest digest. They are different hashes and will not match. ## Multi-architecture wrinkle For a multi-platform image, the tag points at an **image index** (also called a manifest list): a small document listing one manifest digest per platform. So `myapp:1.4` → index digest → per-platform manifest digest → layers. When you pin, prefer the *index* digest: it is still immutable, and it still lets an arm64 node and an amd64 node each pull the right variant. Pinning a per-platform manifest digest works too, but it hard-codes the architecture, which usually breaks a mixed fleet. ## The tradeoff Digests are unreadable and do not update themselves. A repository where every `FROM` is a bare digest tells a reviewer nothing about what version they are looking at, and nothing pulls in the security patch that the base-image maintainer shipped last week. The standard resolution is to write **both**: `FROM node:20.11.1-alpine@sha256:…`. The tag documents intent for humans, the digest is what actually resolves, and an automated dependency bot opens a pull request when the tag starts pointing at a newer digest — so the update becomes a reviewed, dated commit rather than a silent change under a running system. The mental model to keep: *tags are for people, digests are for machines, and the moment where a tag becomes a digest should be an event you record.*