The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
OverlayFS gives a process one merged directory tree built from a writable upper layer and one or more lower layers. In Docker’s legacy overlay2 driver, image layers are lower layers and a container’s changes go into its upper layer. A first write to a file that exists only below can copy the whole file into that writable layer; deleting a file instead adds a marker that hides the lower copy without changing the image.
How OverlayFS turns layers into one filesystem
OverlayFS is a Linux filesystem that combines directory trees. The application sees the mounted merged view, not a list of separate layers. The upper directory (upperdir) is writable; lower directories (lowerdir) are typically read-only. If a name exists in both, the upper object takes precedence. When matching entries are directories, their names are merged, while the upper directory’s metadata hides the lower directory’s metadata. The Linux kernel documentation describes the layer and namespace rules.
For Docker’s overlay2 driver, the image’s read-only filesystem layers make up the lower side, and each container has a writable upper layer. The container interacts with the unified merged directory as its root filesystem. Docker documents support for up to 128 lower OverlayFS layers with this driver; that limit is specific to overlay2, not a universal OverlayFS limit. Docker’s OverlayFS storage-driver documentation explains this mapping.
Free tools Windows power users keep installed
One-click scans. No signup required.
What happens when a container reads or writes a file
Reads can stay in the lower layer
If a file exists only in a lower layer, OverlayFS can serve reads from there without copying it into the container’s writable layer. If an upper copy exists, the merged view uses that version instead.
#1 Best Overall
A write to a lower file triggers copy-up
When an operation requires changing a lower-layer file or its metadata, OverlayFS performs a copy_up. It creates any missing parent directories in upper, creates a corresponding file with metadata, and ordinarily copies the file data and extended attributes. Later operations use the upper object. An attempted read-write open can trigger copy-up even if the application ultimately makes no data change. The kernel documentation covers copy-up behavior.
Docker documents 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 application changes only a small part. This can add latency when the file is large. Subsequent writes to that upper-layer copy do not repeat the initial copy-up. This describes Docker’s documented driver behavior, not a claim that every write to every file copies it. Docker’s driver documentation also recommends volumes for write-heavy workloads because they bypass the storage driver; that is general guidance, not a performance guarantee for a particular application.
Rank #2
How Docker represents deletion: whiteouts and opaque directories
Deleting a file hides it; it does not edit the image
Image layers are left unchanged. To make a lower-layer file disappear from the merged view, the upper layer contains a whiteout for the same name. The kernel documents whiteouts as either a 0/0 character device or a zero-length regular file with the appropriate OverlayFS extended attribute. The whiteout masks the lower entry and is itself hidden from the merged view. The kernel’s OverlayFS documentation describes the marker forms.
Recommended Free Tools
Deleting a directory uses an opaque marker
An opaque directory marker in upper prevents a same-named lower directory from being merged into the visible directory. The lower directory remains on disk in its image layer; it is simply no longer visible at that path through the overlay mount. Marker representation can vary with how layers are constructed, so the on-disk details are not a safe basis for manual edits. Docker warns that its /var/lib/docker/ contents are managed by Docker. See Docker’s storage-driver documentation.
Rank #3
Optional kernel behavior: metadata-only copy-up
The Linux kernel supports an optional metacopy feature. With it, a metadata-only operation such as chmod or chown can first copy up metadata without copying file data; data is copied later if a write requires it. The kernel uses an OverlayFS extended attribute to mark this state and cautions against enabling the feature when upper or lower directories are untrusted. This is an optional kernel capability, not evidence that Docker enables it by default. The kernel documentation details metacopy.
Why renaming a directory can return EXDEV
Renaming a lower or merged directory may fail with EXDEV under the default behavior. Kernel redirect_dir configuration provides another path, but whether it is available depends on configuration. Docker’s overlay2 documentation says directory renames are allowed only when the 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 rule that every rename fails. Kernel rename behavior and Docker’s driver notes give the relevant context.
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. Existing installations and configurations may still use overlay2; the Engine version and image-store configuration determine which implementation is active. The distinction matters because Docker’s overlay2 details should not automatically be applied to every Docker deployment. Docker’s current documentation describes its status.
Quick Recap
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
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.
