OverlayFS Explained: Linux Container Image Layers

Updated on Oct 29, 2026

9 min read

OverlayFS is the Linux filesystem mechanism behind many container storage setups, but its terms—lower layers, an upper layer, copy-up, and whiteouts—are easy to confuse with the image format itself. Developers and platform operators encounter it when a container filesystem appears writable even though its image is built from read-only layers. Understanding the boundary explains why a small write can consume more disk than expected, why deleting an image file does not edit the image, and when persistent storage needs a volume instead.

What Is OverlayFS?

OverlayFS is a union filesystem in the Linux kernel. It combines directory trees from one or more lower layers with an optional writable upper layer, then presents the result as one merged directory tree. Applications use the merged view as if it were an ordinary filesystem; the underlying layers remain separate.

The Linux kernel OverlayFS documentation describes its mount options, supported behavior, and limitations. A mount commonly uses four paths:

Lower directory (lowerdir): supplies read-only base content. A mount may stack multiple lower directories.
Upper directory (upperdir): stores new or changed files and markers for removed lower files.
Work directory (workdir): a private directory OverlayFS uses for operations involving the upper layer. It must be on the same filesystem as the upper directory.
Merged mount: the single filesystem view applications access.

OverlayFS is a Linux filesystem feature, not a Docker-specific image format. The Linux kernel project publishes the kernel that provides it; the host kernel and its configuration determine which features are available.

Why Does OverlayFS Matter for Containers?

Container images are usually assembled from reusable filesystem layers. A running container needs a view of those files and somewhere to place changes, without modifying the shared image. OverlayFS can combine read-only image content with a per-container writable layer, allowing several containers to reuse lower content while keeping their writes separate.

This design supports efficient storage reuse, but it does not make writes free or data persistent. A container process may see an ordinary path while the runtime performs filesystem work underneath. A write to a file that exists only in a lower layer may trigger copy-up: OverlayFS creates an upper-layer version before allowing the change. The new data belongs to that container’s writable layer, which is normally discarded when the container is removed.

For data that must outlive a container, use a volume or another explicit storage system. OverlayFS is part of the container’s root filesystem implementation, not a backup or database storage policy.

How Image Layers and OverlayFS Fit Together

The OCI Image Specification defines an image as a manifest, configuration, and filesystem layer changesets. Its layer specification describes how those changes are serialized and applied. OverlayFS instead defines how Linux can expose directory trees together at runtime. An OCI image can be unpacked and run without OverlayFS, and an OverlayFS mount can combine directories that did not come from a container image.

Feature	OCI image layer	OverlayFS layer
What it represents	A portable filesystem changeset, commonly distributed as a tar archive	A directory tree participating in a Linux union mount
Where it exists	In an image or registry as content identified by its descriptor	On the host filesystem as a lower, upper, or work directory
How ordering works	Image configuration and manifest describe the ordered changesets	Mount options define lower-directory precedence; upper content takes priority
How writes work	An image layer is content-addressed and is not modified in place	Writes to lower-only files generally create an upper copy
How removals work	A changeset encodes removals using OCI whiteout entries	OverlayFS records a whiteout in the upper layer to hide a lower name
Scope	Image distribution and filesystem changes	One runtime’s filesystem composition on Linux

The distinction matters when debugging storage. Seeing an OverlayFS mount does not mean each directory is a separate image layer, and an OCI layer archive is not itself an OverlayFS mount. A runtime can unpack, transform, snapshot, or otherwise manage image content before exposing a container root filesystem.

In a basic mount, lookups check the upper layer first, then the lower layer or layers. If the same non-directory path exists in both, the upper version hides the lower one. If a directory exists in both, OverlayFS can merge their directory entries. With multiple lower directories, the leftmost lower directory in the mount option has the highest precedence among the lowers.

             process reads and writes
                       |
                 merged view
                       |
      +----------------+----------------+
      |                                 |
  upperdir (writable)       lowerdir(s) (read-only)
      |                                 |
 new/changed files          image and base content
 whiteouts                  hidden when overridden

In Docker, the OverlayFS storage driver documentation explains how a Linux Engine can use OverlayFS for its container filesystem. The driver name and implementation depend on the Engine’s storage configuration: the classic overlay2 driver and the overlayfs snapshotter used with Docker’s containerd image store are related but should not be assumed to have identical setup or on-disk layouts.

Key OverlayFS Operations

Copy-up

Reading a lower-layer file does not normally copy it. When a process opens a lower-only file for writing or changes certain metadata, OverlayFS can create an equivalent file in upperdir. With the default data copy-up behavior, this includes copying the file’s contents. Subsequent writes operate on the upper copy, leaving the original lower file unchanged.

This has practical consequences: the first modification of a large file can use substantially more space and time than a small write would suggest. Some OverlayFS configurations support metadata-only copy-up, which delays copying file data until a write actually needs it. Availability and compatibility depend on the kernel, mount options, and runtime, so do not assume that a container engine enables it.

Whiteouts and opaque directories

Removing a file that exists only in a lower directory cannot erase that read-only source. Instead, OverlayFS records a whiteout in the upper directory. The merged view hides both the marker and the matching lower file. An opaque upper directory similarly prevents a lower directory with the same name from contributing entries.

OCI layers also encode removals as whiteouts, but their archive representation is defined by the OCI specification. That is not the same as the kernel’s on-disk whiteout representation. The runtime translates or applies image changesets as needed; operators should not manipulate whiteout files or runtime-managed layer directories by hand.

Filesystem requirements and behavior

OverlayFS imposes requirements on the backing filesystem. In particular, a writable upper filesystem must support the extended attributes OverlayFS needs and provide valid directory-entry type information; the work directory must share the upper filesystem. Docker documents additional prerequisites for its own storage driver, including backing-filesystem details.

OverlayFS also has behavior that differs from a single native filesystem. Copy-up, merged directory metadata, inode reporting, hard links, and renames can affect applications that inspect low-level filesystem details. The kernel documentation describes those limitations and mount options. Test workloads that depend on filesystem identity, hard links, or unusual rename behavior against the actual kernel and runtime configuration.

Where Container Runtimes Use It

The most familiar use is a Linux container root filesystem: image content forms one or more lower layers, while a container’s writable layer supplies its changes. This makes creating and removing containers relatively cheap when they mostly read shared base files.

Build systems and container runtimes may also use layered snapshots to reuse filesystem content across builds or containers. The precise implementation depends on the runtime. For example, container image lazy loading and remote snapshotters explains an alternative approach that can fetch image data on demand; OverlayFS is about composing local directory trees, not retrieving missing image bytes remotely.

OverlayFS should not be confused with Docker’s network overlay driver, which connects containers across hosts. Nor does an OverlayFS mount by itself provide persistence for databases. For those broader storage choices, see the container storage guide and Docker volumes vs. bind mounts.

Practical Guide: Mount and Inspect a Test Overlay

The following demonstration requires a Linux host with OverlayFS enabled and permission to mount filesystems, typically through sudo. It uses a fresh temporary directory; do not point these commands at Docker’s data directory or a production path.

Create one lower tree and the directories required for an upper layer and mount:

BASE="$(mktemp -d)"
mkdir -p "$BASE/lower/etc" "$BASE/upper" "$BASE/work" "$BASE/merged"
printf 'original\n' > "$BASE/lower/etc/message"

sudo mount -t overlay overlay \
  -o "lowerdir=$BASE/lower,upperdir=$BASE/upper,workdir=$BASE/work" \
  "$BASE/merged"

The merged path initially reads the lower file. Write through the merged mount, then inspect the upper tree to see where the changed file was created:

cat "$BASE/merged/etc/message"
printf 'changed in upper\n' | sudo tee "$BASE/merged/etc/message" >/dev/null
cat "$BASE/merged/etc/message"
sudo find "$BASE/upper" -type f -print

The last command should include an upper copy of etc/message; the original lower file remains unchanged. To remove the mount and test files when finished:

sudo umount "$BASE/merged"
sudo rm -r "$BASE"

To inspect an existing Docker host without modifying its storage, check the selected driver and current OverlayFS mounts:

docker info --format 'Storage driver: {{.Driver}}'
findmnt -t overlay
df -h
df -i

If a container write fails or consumes unexpected space, check available bytes and inodes, then inspect the Docker service logs and kernel messages. A driver or backing-filesystem mismatch may appear in those logs. Do not repair a problem by editing files under Docker’s managed data directory; use supported Docker commands and back up any data before changing storage configuration.

Common Misconceptions

“An image layer is the same thing as an OverlayFS directory”

No. OCI image layers are serialized changesets used to distribute image content. OverlayFS layers are directory trees mounted together by the Linux kernel. A runtime may use OverlayFS to present unpacked image content, but the concepts and representations are separate.

“A container write changes its image”

No. A write to a lower-only file creates or modifies the container’s upper layer. Other containers using the image do not see that change, and committing a new image is a separate operation.

“The writable layer is a durable volume”

No. It is a convenient layer for container-local changes, not a data lifecycle guarantee. Store important state in a separately managed volume or storage service and plan backups independently.

Docker containers explained traces images, runtimes, storage, and deployment.
Container storage concepts compares ephemeral and persistent storage options.
Docker volumes vs. bind mounts explains durable and host-provided container mounts.
Container image lazy loading and remote snapshotters compares local layering with remote, on-demand reads.

Changelog

First published 2026-10-29.