Free tools Windows power users keep installed
One-click scans. No signup required.
OverlayFS gives a process one merged filesystem view over multiple directory trees. In Docker’s legacy overlay2 driver, image layers are read-only lower directories and a container adds a writable upper directory. Reading a lower-layer file does not normally copy it; changing that file can trigger copy-up into the upper layer, while deletion is recorded with a whiteout rather than by altering the image.
How OverlayFS turns layers into one filesystem
OverlayFS is a Linux union filesystem: it combines an upper directory tree with one or more lower directory trees and exposes the result through a merged mount. Applications use the merged path as though it were an ordinary filesystem. The upper tree is writable; lower trees are typically read-only.
As an Amazon Associate I earn from qualifying purchases.
If a name exists in both upper and lower, the upper object takes precedence. When both objects are directories, OverlayFS merges their entries, but metadata for the directory comes from the upper directory. The Linux kernel documentation describes the rule this way: “When a name exists in both filesystems and refers to a non-directory in either, then the lower object is hidden – the name refers only to the upper object.” Linux kernel documentation: Overlay Filesystem.
How that maps to Docker
With Docker’s overlay2 storage driver, an image’s read-only filesystem layers make up the lower side. Each container gets a writable upper layer, and the merged directory presents the container’s apparent root filesystem. Docker documents support for up to 128 lower OverlayFS layers for this driver; that is an overlay2-specific documented limit, not a universal limit for every OverlayFS setup or Docker storage backend. Docker Docs: OverlayFS storage driver.
#1 Best Overall
What happens when a container reads or writes a file?
Reading a lower-layer file
If a file exists only in a lower layer, OverlayFS can serve reads from that layer without first copying the file into the container’s writable layer. If an upper copy with the same name exists, the upper version is used.
Writing a lower-layer file: copy-up
A lower layer cannot be changed in place. When an operation needs to modify a lower-layer file, OverlayFS performs copy_up: it creates any required parent directories in upper, makes a corresponding upper file with metadata, and ordinarily copies the file’s data and extended attributes. Later operations use the upper copy. Even opening a file for read-write access may cause copy-up, although the program ultimately makes no data change. Linux kernel documentation: Overlay Filesystem.
Rank #2
Docker’s documentation describes overlay2 copy-up as file-level: the first write to an existing lower-layer file copies the whole file into the container’s writable layer, even if the program changes only a small part. A large file can therefore add latency on that first write. Subsequent writes to the already-copied file do not repeat the initial copy-up. This is documented behavior, not a benchmark or a guarantee of a particular delay on every system. Docker Docs: OverlayFS storage driver.
So, does Docker copy the whole file when one byte changes? For the documented overlay2 behavior, the first write to a lower-layer file can copy the whole file; it does not copy the file afresh on every later write. The Linux kernel also has optional metadata-only copy-up behavior, so kernel-level details depend on configuration rather than being identical in every OverlayFS deployment.
Rank #3
Metadata changes and optional metacopy
The kernel’s optional metacopy feature can copy up metadata for operations such as chmod or chown without immediately copying file data. Data is copied later if a write requires it. The kernel marks this state with an OverlayFS extended attribute and warns against enabling the feature when upper or lower directories are untrusted. Do not assume metacopy is enabled by default in Docker. Linux kernel documentation: Overlay Filesystem.
What a whiteout means when a file is deleted
Deleting a file that came from a lower layer cannot remove it from that read-only layer. Instead, the upper layer records a whiteout that hides the lower entry of the same name in the merged view. The whiteout is itself hidden from applications looking through that merged mount.
At the kernel level, a whiteout can be represented as a character device with device number 0/0 or as a zero-length regular file with the appropriate OverlayFS extended attribute. The exact on-disk representation can vary with how layers were constructed. Linux kernel documentation: Overlay Filesystem.
Deleting a directory
For a directory, an opaque-directory marker in upper prevents OverlayFS from merging in a same-named lower directory. The lower directory and its contents remain in the image layer; they are simply no longer visible at that path through the merged mount.
Best Value
- Docker, Docker Swarm, Docker Compose, Programmer, Developer, Coding, Programming, Software Engineer, Code, DevOps, Deploy, Deployment, Kubernetes, Salt, Puppet, Chef, Terraform, Container, AWS, Azure, Cloud, Geek, Funny, Computer, Software, Tech, IT
- Integration, Scrum, Compile, Compilation, Science, Bug, Debug, Python, Linux, Java, Javascript, Scala, Dotnet, Kotlin
- Lightweight, Classic fit, Double-needle sleeve and bottom hem
These markers explain why browsing an image layer’s storage does not necessarily show a straightforward record of the merged filesystem. Docker warns that its /var/lib/docker/ contents are managed by Docker. Do not hand-edit storage-driver directories to remove files or markers; use Docker-managed operations instead. Docker Docs: OverlayFS storage driver.
Why renaming a directory can return EXDEV
Renaming a lower-layer or merged directory can fail with EXDEV by default. The kernel’s redirect_dir feature provides another behavior, but it depends on configuration. Docker’s overlay2 documentation says directory renames are allowed only when both source and destination are on the top layer, and advises applications to handle EXDEV with a copy-and-unlink fallback. This is a compatibility caveat, not a claim that every rename fails. Linux kernel documentation: Overlay Filesystem and Docker Docs: OverlayFS storage driver.
Is Docker still using overlay2?
Not as the default for every current installation. Docker’s storage-driver documentation says Docker Engine 29.0 and later uses the containerd image store by default and describes overlay2 as a legacy storage driver superseded by the overlayfs containerd snapshotter. The active implementation depends on the Engine version and image-store configuration. The overlay2 model remains relevant for understanding existing installations and Docker documentation, but it should not be assumed to describe every current Docker deployment. Docker Docs: OverlayFS storage driver.
Quick Recap
What this means for container workloads
- Read-heavy access: A lower-layer file can be read without first copying it into the writable layer.
- First write to an image file: Under documented
overlay2behavior, copy-up is file-level, so the initial change to a large lower-layer file can involve copying that whole file. - Repeated writes: Once the file is in upper, later writes use that copy rather than repeating the original copy-up.
- Write-heavy application data: Docker recommends volumes for write-heavy workloads because they bypass the storage driver; this is general guidance, not a workload-specific performance result. Docker Docs: OverlayFS storage driver.
- Application portability: Code that renames directories should account for
EXDEVwhere the relevant OverlayFS configuration or Docker driver may return it.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
