What is Overlayfs
Overlayfs is a union filesystem built into the Linux kernel that merges multiple directory trees into a single unified view. Container runtimes use overlayfs to stack read-only image layers with a writable layer on top, creating the container's root filesystem.
How it works
Overlayfs has three directory types:
- Lower directories — the read-only image layers, stacked in order. These are never modified.
- Upper directory — the writable layer. All runtime changes (new files, modifications, deletions) go here.
- Merged directory — the unified view presented to the container. Reads search the upper layer first, then fall through lower layers until the file is found.
When a container modifies a file that exists in a lower layer, overlayfs performs a copy-up: it copies the file to the upper layer before the modification. The lower layer's copy remains unchanged. This is copy-on-write at the filesystem level.
Deleting a file creates a whiteout entry in the upper layer — a special marker that hides the file in the lower layers without actually deleting it. This preserves layer immutability.
Docker uses the overlay2 storage driver by default, which supports up to 128 lower layers. The mount command looks like: mount -t overlay overlay -o lowerdir=layer3:layer2:layer1,upperdir=container,workdir=work merged/.
Why it matters
Overlayfs is why multiple containers can share the same base image without duplicating gigabytes of data. Each container has its own writable upper layer, but the read-only lower layers are shared. This makes container creation instant (no filesystem copy) and disk-efficient.
See How Container Images Work for how overlayfs and image layers interact.