Docker 02. How to Understand Images, Layers, Tags, and Digests

Summary

As soon as you start using Docker, the terms image, layer, tag, and digest appear together everywhere. For beginners, they can all feel like slightly different versions of “the image version.” But they do different jobs. An image is an immutable package, a layer is a filesystem change unit inside that image, a tag is a human-friendly label, and a digest is a content-fixed identifier.

The practical conclusion is simple. Tags are convenient for people and workflows, while digests matter when you need exact reproducibility and deployment pinning. If you trust tags alone, you can easily meet “the same name with different content” later. If you use only digests, daily operations become harder than necessary. In practice, you want both, but for different reasons.

Document Information

• Written on: 2026-04-20
• Verification date: 2026-04-21
• Document type: analysis
• Test environment: Windows PowerShell with Docker Desktop for Windows. After restarting Docker Desktop and the docker-desktop WSL distribution, tests ran on the desktop-linux context with Linux containers.
• Test version: Docker Desktop 4.70.0(224270), Docker CLI/Engine 29.4.0(API 1.54), Docker Compose v5.1.2, Docker Buildx v0.33.0-desktop.1. Docker official docs were checked on 2026-04-20.
• Source grade: official Docker documentation and local reproduced results are used.
• Note: this post does not cover multi-platform manifests or image signing. It stays with the minimum concepts needed to separate tags from digests.

Problem Definition

Beginners usually get stuck at a few recurring points.

• They confuse an image with a container.
• They do not understand what a layer actually represents.
• They treat tags such as latest as if they were fixed versions.
• They see a digest and assume it is too long and too awkward to matter in real work.

This post focuses on the image side of Docker. Registry push flow comes in the next post.

Verified Facts

• According to the official documentation, a container image is a standardized package containing the files, binaries, libraries, and configuration needed to run a container. Evidence: What is an image?
• According to the official documentation, images are immutable and are composed of layers. Evidence: What is an image?
• According to the official documentation, a container gets its own writable layer on top of the read-only image layers, and data in that writable layer does not persist after the container is destroyed. Evidence: Storage
• According to the official documentation, docker image tag creates a new tag that refers to a source image. Evidence: docker image tag
• According to the official documentation, docker image pull prints the digest after a pull, and a digest can be used in place of a tag when pulling an image. Evidence: docker image pull
• According to the official documentation, tags can change while digests are treated as immutable references. Evidence: Image validation

The official CLI examples reduce the tag-versus-digest difference to patterns like these:

docker pull ubuntu:24.04
docker pull ubuntu@sha256:<digest>
docker image tag myapp:1.0 myorg/myapp:stable

The first and third lines are human-friendly naming flows. The second is the exact-content flow.

Directly Reproduced Results

• Directly confirmed result: on 2026-04-21, I pulled alpine:3.20, inspected its RepoDigest, pulled by digest, and created an additional local tag from Windows PowerShell.

docker pull alpine:3.20
docker image inspect alpine:3.20 --format '{{index .RepoDigests 0}}'
docker pull alpine@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc
docker image tag alpine:3.20 codex/alpine-test:verified

• Result summary: the RepoDigest for alpine:3.20 was alpine@sha256:d9e853e87e55526f6b2917df91a2115c36dd7c696a35be12163d44e6e2a4b6bc. Pulling the same digest reported the image as up to date. The local tag codex/alpine-test:verified pointed to the same image ID as alpine:3.20.

Interpretation / Opinion

My view is that the first misconception to fix is “a tag is the version.” A tag can be used like a version label, but it is fundamentally closer to a convenient human-facing pointer. Within one repository, tags such as stable, prod, latest, or even 1.0 can later be moved to point to different image content depending on your release policy.

By contrast, a digest is awkward for people but useful for content pinning. That is the more accurate way to treat it. In operations, the healthiest pattern is often to store both: a readable tag for communication and an exact digest for release records, CI metadata, or deployment manifests.

Layers matter early, too. If you think of an image only as one opaque bundle, it becomes harder to understand build cache and partial rebuild behavior later. If you already understand that an image is made of immutable filesystem layers, Dockerfile and cache behavior become much easier to reason about.

In practice, this four-part model is enough for a beginner:

• image: immutable runtime package
• layer: internal filesystem change unit
• tag: human-friendly mutable label
• digest: content-fixed identifier

Limits and Exceptions

This post does not cover multi-platform images, manifest lists, OCI layout details, or content trust. The explanation of digests here stays within the scope of beginner-level image references.

Also, saying “tags can change” does not mean “never use tags.” Tags are still useful for development, QA, collaboration, and release naming. The real point is that when exact reproducibility matters, you should record the digest alongside the tag.

The direct reproduction used a single alpine:3.20 image reference. I did not separately test multi-platform images, manifest lists, OCI layout details, or content trust. The general tag-and-digest explanation is limited to the Docker documentation and the local command results above.

References

• Docker Docs, What is an image?
• Docker Docs, Storage
• Docker Docs, docker image pull
• Docker Docs, docker image tag
• Docker Docs, Image validation