2.3.3.1 Union Layer Model
A focused guide to Union Layer Model, connecting core concepts with practical Docker and container operations.
The union layer model is the specific arrangement of stacked, ordered filesystem layers that together define an image's contents — each layer representing a discrete set of changes relative to the layer below it, combined by a union filesystem into one coherent view.
Layers as an Ordered Sequence of Changes
Each instruction in a Dockerfile that modifies the filesystem produces a new layer, and the image as a whole is the ordered sequence of every layer from its base image through to its final instruction.
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y curl
COPY app.py /app/app.py
CMD ["python3", "/app/app.py"]
docker history myapp:1.0
The history command lists these layers in order, showing exactly which instruction produced each one and how much it added to the image's total size.
Why Order Matters
Because layers are applied in sequence, a later layer that modifies a file from an earlier layer effectively overrides it in the merged view — the union layer model resolves conflicts between layers by always preferring the most recently applied one for any given file path.
RUN echo "v1" > /etc/version
RUN echo "v2" > /etc/version
The resulting image reports /etc/version as containing v2, since the second layer's change takes precedence in the merged view, even though the first layer's change to the same file still exists in the image's lower layer.
Layer Reuse Across Builds
Because each layer is identified by the content it produces, identical instructions executed in the same order across different builds can produce identical, reusable layers, which is the basis for Docker's build cache.
docker build -t myapp:1.0 .
docker build -t myapp:1.1 .
If only the final instructions of the Dockerfile changed between these two builds, earlier, unaffected layers are reused directly from the cache rather than rebuilt.
Why the Union Layer Model Matters
This layered, ordered model is what allows Docker to build images incrementally and efficiently, cache and reuse unchanged portions of a build, and let multiple images share common base layers — all of it grounded in the simple principle that an image is nothing more than an ordered stack of filesystem changes.