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.
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:
| Image | Container | |
|---|---|---|
| Nature | Read-only template | Running (or stopped) instance |
| Layers | Stack of read-only layers | Image layers + one writable layer |
| Count | One image | Many containers from one image |
| Persistence | Immutable | Writable 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
latestin 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
RUNor lateCOPY . .. 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
COPYa 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.