2.3.3 Union Filesystem Model

The union filesystem model is the approach Docker uses to combine multiple read-only image layers and a writable layer into what appears, from inside a container, to be a single, ordinary filesystem — implemented on Linux through the kernel's overlay filesystem.

Layers Stacked, Not Copied

Each layer in an image represents a set of filesystem changes relative to the layer beneath it. Rather than copying the contents of every layer into a single combined filesystem, the union filesystem model presents a merged view computed on demand, with each underlying layer remaining unchanged and independently stored.

docker history myapp:1.0

This lists each layer that makes up an image, in the order they are stacked, with each layer's storage remaining entirely separate.

How the Merged View Is Constructed

When a file is requested from a container's filesystem, the overlay filesystem looks for it starting from the topmost layer and working downward, returning the first instance it finds — which is how a file modified in a later layer correctly takes precedence over an earlier version of the same file from a lower layer.

docker run --rm myapp:1.0 cat /etc/config.yaml

If /etc/config.yaml exists in both the base image and a later layer that modified it, this command returns the version from the topmost layer that contains it.

The Writable Layer on Top

Every running container has its own thin writable layer, sitting above all of its image's read-only layers. Any file the container creates or modifies is written here, leaving the underlying image layers completely untouched.

docker run -d --name myapp myapp:1.0
docker exec myapp sh -c "echo data > /tmp/file.txt"
docker diff myapp

docker diff reports exactly the changes present in this container's own writable layer, distinct from anything in the image it was started from.

Efficient Sharing Across Containers

Because read-only layers are shared rather than duplicated, multiple containers started from the same image — or from different images sharing common base layers — consume disk space only for their own writable layers, not for redundant copies of shared, unchanged layers.

docker run -d myimage:1.0
docker run -d myimage:1.0

Both containers share the exact same underlying image layers on disk, each paying only the small cost of its own writable layer.

Why the Union Filesystem Model Matters

This model is what makes containers based on the same or related images both fast to start (no copying of layer data) and efficient to store (shared layers are stored once), directly enabling the practical density and speed that make containers attractive at scale.