What Is an Overlay File System?

Layered storage directories merging into one unified file system view

Overlay File System Explainer

An overlay file system combines two or more directory trees into one merged view. A lower layer usually contains a base set of files and may be read-only. An upper layer stores changes and must be writable, while a work directory supports internal operations. When a process looks through the merged mount, files from the upper tree take precedence and other names fall through to the lower tree. This arrangement is widely used for container images, live systems, and environments that need cheap writable variants of a common base.

Reading an unchanged file can use the lower layer directly, so many merged environments can share one underlying copy. Creating a new file places it in the upper layer. Modifying a lower-only file triggers copy-up: the overlay first creates a corresponding upper object with the required data and metadata, then the change applies to that upper copy. Later reads find the upper version and hide the original below. Copy-up may occur on the first write-like operation, even if only metadata changes, and can be expensive for large files.

Deletion cannot normally remove a read-only lower object, so the upper layer records a whiteout or opaque directory marker that hides it from the merged view. The lower file still physically exists and may reappear if the overlay is mounted without that upper layer. Renames and directory operations require special care because the apparent unified tree is assembled from distinct storage locations. Implementations define rules for redirecting directories, copying metadata, and representing hidden children while preserving expected path behavior.

The merged view can create identity surprises. Before copy-up, a file may be represented by a lower inode; afterward, the visible object is an upper inode. Programs that assume stable device and inode numbers, hold long-lived handles, watch file events, or rely on unusual locking semantics need testing. Not every lower or upper file system is suitable, and required support for extended attributes, directory entry types, or other features must be present. The work directory and upper directory generally need to reside on the same file system.

Container runtimes use layers to distribute common application components efficiently. A base operating-system layer can be shared, later image layers add packages or configuration, and a thin writable layer records each running container’s changes. That writable layer is not automatically durable application storage. Databases and user data are often placed on volumes with clearer persistence and performance behavior. Removing a container can remove its writable layer even though the immutable image remains available.

An overlay is not the same as a backup, snapshot, or security boundary. Lower files remain accessible to privileged code outside the merged view, and sensitive data copied into an upper layer still needs protection. Deep layer stacks, many small metadata operations, and copy-up of large files can affect performance. Administrators need to understand where actual bytes reside, how free space is accounted, and what cleanup removes. The overlay’s useful abstraction is precedence: assemble a unified namespace from shared lower content and a private upper set of additions, replacements, and hiding markers, allowing many writable views without duplicating the complete base tree at the start.

Image construction rewards stable layering. Instructions that change frequently are placed later so rebuilding them does not invalidate reusable earlier layers, and large temporary files should be removed within the same construction step that creates them. Otherwise hidden lower-layer data may continue consuming storage even after the merged view shows deletion. Layer digests make content addressable and shareable, but secrets copied into a layer can remain recoverable from image history. Secure build systems keep credentials outside the layer graph, scan every layer, and publish a new immutable image instead of modifying one running container by hand.

An overlay file system merges lower directory trees with a writable upper tree into one view. Key terms include lower layer, upper layer, work directory, merged mount, copy-up, whiteout, opaque directory, inode, image layer, and writable layer.

The overlay copies the file into the upper layer and applies the change there. The new upper object takes precedence in the merged view, while the original lower file remains unchanged underneath.

Because the lower layer may be read-only, the upper layer stores a whiteout or related marker that hides the lower name. The underlying file still exists and is visible outside that particular merged view.

Explore more "Explainers"

Discover additional explainers across politics, science, business, technology, and other fields. Each explainer breaks down a complex idea into clear, everyday language—helping you better understand how major concepts, systems, and debates shape the world around us.