Skip to main content
Docker·7 min read

Docker Images Explained — Layers, Tags, Digests, and Registries

A deep, practical guide to Docker images: what an image actually is, how read-only layers stack under the writable container layer, image vs container, tags vs digests, registries, and inspecting images with docker image, history, and inspect.

DT

DevOps Engineer & Technical Writer

The Problem

A Docker image feels like a black box: you run docker build, something appears, and docker run turns it into a container. But not understanding the structure underneath leads to real pain — bloated images, broken cache, confusion over why two "latest" tags behave differently, and surprise when data disappears after a container restarts. The fix is understanding that an image is a stack of read-only layers, and a container is just that stack plus one thin writable layer on top.

DOCKER IMAGE LAYERS + CONTAINER WRITABLE LAYER IMAGE (read-only, shared) LAYER 1 · BASE FROM node:20-alpine LAYER 2 · DEPS RUN npm ci LAYER 3 · APP CODE COPY . . WRITABLE LAYER (per container) logs, tmp files, changes CONTAINER = image + this layer SHARING + IDENTITY TAG (mutable pointer) myapp:1.0 → sha256:9f2a… DIGEST (immutable) sha256:9f2a4c… content hash Many images share LAYER 1 on disk — a layer is stored once, reused everywhere

What an Image Actually Is

A Docker image is a read-only template built from a stack of layers plus a small JSON manifest and config. Each instruction in a Dockerfile that changes the filesystem (FROM, COPY, RUN, ADD) produces a new layer. A layer records only the difference from the layer below it. Stack them and you get a complete filesystem.

Layers are content-addressed by a SHA-256 hash, which has two big consequences:

  • Sharing: if two images use FROM node:20-alpine, that base layer is stored on disk exactly once and shared.
  • Caching: if a layer's inputs are unchanged, Docker reuses the cached layer instead of rebuilding it.

Image vs Container

This is the distinction that trips up most newcomers:

ImageContainer
NatureRead-only templateRunning (or stopped) instance
LayersStack of read-only layersImage layers + one writable layer
CountOne imageMany containers from one image
PersistenceImmutableWritable layer is discarded on removal
Command<code class="inline-code">docker build</code> / <code class="inline-code">docker pull</code><code class="inline-code">docker run</code>

When you docker run myapp:1.0, Docker takes the image's read-only layers and adds a thin writable layer on top. Everything the process writes — logs, temp files, uploaded data — lands in that writable layer. Remove the container and that layer is gone. This is exactly why databases need volumes.

Tags vs Digests

A tag is a human-friendly, mutable pointer to an image, like myapp:1.0 or nginx:latest. Someone can push a different image to the same tag tomorrow, so a tag is not a guarantee of identical content.

A digest is an immutable content hash of the image, like sha256:9f2a4c…. The same digest always means the exact same bytes.

# Pull by tag (may change over time)

docker pull nginx:1.27

# Pin by digest for reproducible deployments

docker pull nginx@sha256:9f2a4c3b1d...

# See the digest of a local image

docker images --digests nginx

For production and CI, pin critical images by digest so a surprise latest push can never change what you deploy.

Registries

A registry stores and distributes images. docker push uploads layers; docker pull downloads only the layers you do not already have locally.

# Tag an image for a registry

docker tag myapp:1.0 registry.example.com/team/myapp:1.0

# Authenticate and push

docker login registry.example.com

docker push registry.example.com/team/myapp:1.0

Common registries include Docker Hub, GitHub Container Registry (ghcr.io), Amazon ECR, and Google Artifact Registry. The full image reference is registry/namespace/repository:tag.

Inspecting Images

List and size

docker images

docker image ls --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

Layer history

docker history shows every layer, the instruction that created it, and its size — the fastest way to find a bloated layer.
docker history myapp:1.0 --no-trunc

Full metadata

docker inspect dumps the complete config as JSON: layers, environment, entrypoint, exposed ports, and more.
docker image inspect myapp:1.0

docker image inspect myapp:1.0 --format '{{json .RootFS.Layers}}'

Clean up dangling layers

docker image prune        # remove dangling (untagged) images

docker image prune -a # remove all images not used by a container

How Caching and Sharing Work Together

Because layers are keyed by content, Docker's build cache reuses any layer whose inputs have not changed. Ordering matters: put instructions that change rarely (installing dependencies) before instructions that change often (copying source). Then a one-line code change only rebuilds the top layer, and the base plus dependency layers stay cached and shared across every image on the host.

Common Mistakes to Avoid

  • Relying on latest in production. It is just a tag and can silently change. Pin a version or a digest.
  • Expecting container writes to persist. The writable layer is destroyed with the container. Use a volume for anything you must keep.
  • One huge RUN or late COPY . .. Poor layer ordering wrecks the cache and inflates rebuild time. Order from least to most frequently changing.
  • Confusing image size with number of layers. Fewer layers is not automatically smaller. What matters is the total content; a tidy multi-stage build beats a hand-squashed one.
  • Leaking secrets into a layer. Anything added in one layer and deleted in a later layer still exists in the earlier layer's history. Never COPY a secret into an image.

FAQ

What is the difference between a Docker image and a container?

An image is a read-only template made of stacked layers. A container is a running instance of that image with an added writable layer on top. You can create many containers from a single image, and each one's writable layer is independent and discarded when the container is removed.

Why are Docker image layers read-only?

Read-only layers can be safely shared and cached across images and containers. If two images share a base layer, it is stored once on disk, which saves space and makes pulls faster. The container's writable layer isolates per-container changes without altering the shared image.

What is the difference between a tag and a digest?

A tag is a mutable, human-readable label like myapp:1.0 that can be repointed to a different image later. A digest is an immutable SHA-256 hash of the image content; the same digest always refers to identical bytes. Pin by digest when you need guaranteed reproducibility.

How do I find out why my image is so large?

Run docker history <image> --no-trunc to see the size contributed by each layer and the instruction that created it. Large layers usually come from installing build tools, caching package manager data, or copying unnecessary files. A .dockerignore and a multi-stage build are the usual fixes.