Before touching any internals, it helps to place overlay2 correctly: it is not Docker, it is not a filesystem you format a disk with, and it is not unique to Docker.

The one-sentence definition

overlay2 is Docker’s default storage driver on Linux — a piece of software that tells the Docker engine how to store image layers and container filesystems on disk using the Linux kernel’s built-in OverlayFS filesystem. It is not something you install separately; it has shipped inside the Linux kernel since version 3.18 (merged, stable form arrived around 4.0+), and Docker simply calls into it through kernel mount syscalls.

A brief history, in plain terms

OverlayFS itself started life as an out-of-tree kernel patch used by early Linux live-CD and embedded-systems projects, long before containers were mainstream — those projects needed a cheap way to let a read-only base system appear “writable” during a live session. Docker’s earliest releases actually shipped with the older, patch-dependent aufs driver instead, because at the time OverlayFS wasn’t yet merged into mainline Linux. Once OverlayFS landed in the mainline kernel and later gained multi-lowerdir support, Docker migrated its default to overlay2, and the ecosystem has broadly stayed there ever since.

overlay2 belongs to a family of technologies called union filesystems (or union mounts). Understanding this family explains almost everything that follows.

What is a union filesystem?

A union filesystem lets you take several separate directories, stack them logically, and present them to the operating system as one single, merged directory — without physically copying any files between them. If the same filename exists in two of the stacked directories, the topmost one “wins” and is the one users see. This merging happens live, in the kernel, every time a process reads that directory.

The four directories overlay2 juggles

Every single OverlayFS mount — whether for an image layer or a running container — is built from four directory roles. Learning these four names is non-negotiable for understanding overlay2, because every log message, every troubleshooting guide, and every docker inspect output refers to them directly.

How directory listings actually get merged

When a process asks to list the contents of a directory in the merged view, the kernel doesn’t just show the topmost layer’s version and stop — it walks every lowerdir that also contains a directory of the same name, at the same path, and combines all of their entries into one listing, with upperdir’s version of any given filename taking priority whenever the same name appears more than once. A directory that has never been touched by the container might therefore be assembled, live, from pieces scattered across several different image layers, all without the kernel ever writing a merged copy back to disk — the merge is computed on every access, not stored.

All of this theory lives at a very real, very inspectable location on your machine: /var/lib/docker/overlay2.

The directory Docker actually maintains

When Docker is configured to use overlay2, every image layer and every container gets its own subdirectory under /var/lib/docker/overlay2/, named with a long random-looking hash (its layer ID). Inside each of those hash-named folders, Docker keeps the pieces OverlayFS needs.

graph TD
    A["/var/lib/docker/overlay2/"] --> B["l/  (short symlinks)"]
    A --> C["<layer-id-1>/diff  (base OS files)"]
    A --> D["<layer-id-2>/diff  (app dependencies)"]
    A --> E["<layer-id-3>/diff  (app code)"]
    A --> F["<container-id>/diff  (writable layer)"]
    A --> G["<container-id>/work  (kernel scratch)"]
    A --> H["<container-id>/merged  (unified view container sees)"]
    B -. "short alias" .-> C
    B -. "short alias" .-> D
    B -. "short alias" .-> E
    H --> F
    H --> E
    H --> D
    H --> C
        

The identity trio: RepoDigests, DiffIDs, and layer IDs

It’s worth knowing that the hash-named folder you see on disk is not the same hash you see with docker images. An image layer actually has three related identities: a content hash for the compressed layer as distributed over the network, a “DiffID” hash for the uncompressed content, and the local overlay2 cache-id used purely for the folder name on this particular machine. Docker keeps a small internal database mapping between all three so it never has to re-download or re-extract a layer it already has.

The metadata database backing all of this

Alongside the layer folders themselves, Docker’s image and layer store maintains its own small embedded database (historically BoltDB-based, under /var/lib/docker/image/overlay2/) that records, for every layer, which parent it stacks on, its DiffID, its size, and its local cache-id. This is the piece of bookkeeping that lets commands like docker history reconstruct a full, ordered layer chain for an image, and it’s exactly why manually deleting a layer folder by hand — bypassing Docker entirely — is dangerous: the database still thinks the layer exists, and a wide range of subsequent operations can fail or misbehave once the two disagree.

Two mechanisms — copy-up and whiteout files — do essentially all of the heavy lifting inside overlay2. Master these two and the rest of the driver’s behavior becomes predictable.

Copy-up: how “editing” a read-only file actually works

Since lowerdirs are strictly read-only, what happens when a process inside a container tries to modify a file that currently lives in a lower (image) layer? The kernel performs an operation called copy-up: it copies the entire file, unmodified, from whichever lowerdir it currently lives in, up into the container’s upperdir — and only then applies the requested change to that new copy. From that point on, every read of that file is served from the upperdir copy, because upperdir always takes priority in the merged view.

Whiteout files: how deletion is faked

Because lowerdirs can never be modified, overlay2 can’t literally erase a file that exists in a lower layer. Instead, when a container “deletes” such a file, the kernel creates a special marker inside upperdir called a whiteout — a character device file with device number 0/0, sharing the same name as the file being hidden. When OverlayFS builds the merged view, it sees the whiteout marker and simply omits that filename from the presented listing, even though the original still physically exists, untouched, down in the lowerdir.

Opaque directories: hiding an entire folder

A related trick handles the case of deleting or replacing an entire directory rather than a single file. overlay2 marks a directory as opaque by setting a special extended attribute (trusted.overlay.opaque=y) on the upperdir copy of that folder. An opaque directory tells the kernel to stop looking further down into any lowerdirs for that folder’s contents — effectively resetting it, which is exactly the behavior Dockerfile instructions like removing and recreating a directory rely on.

A note on hard links across layers

Hard links are files that share the same underlying data on a native filesystem, and they behave a little differently once layers get involved. A hard link created entirely within a single layer works exactly as expected. But if a file that already exists in a lower layer gets a new hard link created against it from inside a running container, the kernel can’t create a true hard link that spans a read-only lower layer and a writable upper layer — instead, it performs a copy-up of the target file into upperdir first, and the new link is created against that upperdir copy. The result is correct from the application’s point of view, but it’s another situation, alongside plain file edits, where an operation that looks cheap on a native filesystem quietly costs a full copy-up on overlay2.

sequenceDiagram
    participant P as Process in container
    participant M as merged view
    participant U as upperdir
    participant L as lowerdir (image layer)
    P->>M: write("/etc/config.txt", newData)
    M->>U: does config.txt exist in upperdir?
    U-->>M: no
    M->>L: copy-up config.txt (full file)
    L-->>U: file copied into upperdir
    M->>U: apply write to upperdir copy
    U-->>P: write succeeds
    Note over L: original in lowerdir is never touched
        

Tracing a container from docker pull to docker rm shows exactly when and where overlay2 gets involved at each stage.

The optional seventh step: turning a container’s changes into a new image

There’s one more transition worth understanding, even though it happens less often in normal workflows: committing a running or stopped container into a brand-new image. When this happens, Docker takes everything currently sitting in that container’s upperdir — including any whiteout markers recording deletions — and packages it as a fresh, standalone image layer, placed on top of the exact lower layers the container was already using. That new layer gets its own content digest and can now be pushed, shared, or used as the base for further containers, exactly like any layer that originated from a Dockerfile instruction. It’s the same copy-up-and-whiteout machinery from earlier chapters, just observed from the image-authoring side rather than the runtime side.

This chapter explains the payoff of the whole design: why ten containers built from the same base image barely use any extra disk space, and why docker build caching is so effective.

Content-addressable layers

Every image layer is identified by a cryptographic hash of its own content. This means if two completely different images both happen to start with, say, the exact same Ubuntu base layer, Docker recognizes the identical hash and stores that base layer’s files exactly once on disk — both images simply reference the same diff folder as one of their lowerdirs.

Why docker build caching works

Each Dockerfile instruction that changes the filesystem (RUN, COPY, ADD) produces one new layer, hashed from its inputs. If you rebuild an image and an earlier instruction’s inputs haven’t changed, Docker reuses that layer’s existing hash from cache instead of re-executing it — which is exactly why Dockerfile authors are taught to put frequently-changing instructions (like copying application source code) near the bottom of the file: it maximizes how many layers above it stay cache-hit on every rebuild.

From manifest to mount: how a chain of hashes becomes a stack of directories

An image’s manifest — the JSON document that a registry actually serves when you pull an image — lists its layers purely as an ordered array of content digests; it says nothing about local folder names at all. When Docker pulls an image, it walks that list top to bottom, and for each digest checks its local metadata database for a matching, already-extracted layer before downloading anything. Only missing layers are actually fetched and decompressed. Once every layer in the chain is present locally, Docker resolves each digest to its local cache-id, and it’s only that final list of cache-ids that ever gets handed to the kernel as the overlay2 mount’s lowerdir string.

This layered chain of identities is what allows the same conceptual “layer” to be verified cryptographically when transferred over the network, deduplicated logically inside Docker’s own bookkeeping, and represented as a short, filesystem-friendly name at the point the kernel actually needs to build a mount — each identity is optimized for the concern at the stage it’s used.

overlay2 is elegant, but it inherits real constraints from both the Linux kernel and the filesystem underneath it. Knowing these limits in advance saves painful production debugging later.

Filesystem feature requirements, explained

The d_type requirement mentioned above deserves a plain-English explanation, because it trips people up in the wild more often than the layer-count limit does. When the kernel scans a directory, each entry can optionally carry a quick hint about what kind of object it is — a regular file, a directory, a symlink — without needing a separate, more expensive lookup call to find out. OverlayFS relies on this hint being present and accurate to correctly merge entries across layers and to know when a whiteout marker is standing in for a deleted directory versus a deleted file. Some older xfs filesystems were formatted with this feature turned off by default, and Docker will refuse to use overlay2 on top of such a filesystem, reporting an explicit error rather than risking silently incorrect behavior.

Nested containers: overlay-on-overlay

A less commonly discussed limitation shows up in Docker-in-Docker setups, where a container itself runs a Docker daemon that also wants to use overlay2 for its own, inner containers. Historically, the Linux kernel restricted or outright refused using an OverlayFS mount as the lowerdir input to another OverlayFS mount, since the underlying filesystem already lacks certain low-level features (like fully generic extended-attribute passthrough) that a second overlay layer depends on. In practice this means nested Docker daemons commonly need to be configured with a different storage driver, or run against a dedicated volume formatted with a fully-featured filesystem, rather than simply inheriting overlay2 by default.

overlay2 became Docker’s default for good reasons, but “default” doesn’t mean “best for every workload.” Here’s the honest balance sheet, followed by how it stacks up against the alternatives.

How it compares to sibling storage drivers

A mental model for reasoning about performance trade-offs

Rather than memorizing specific benchmark numbers — which shift with kernel version, disk hardware, and workload — it’s more durable to reason from the mechanism itself. overlay2 excels whenever a workload’s dominant pattern is “read a lot, occasionally write small, mostly-new files,” because reads hit the shared page cache and writes stay contained to a single small upperdir. It struggles relatively more whenever a workload repeatedly rewrites large, pre-existing files in place, because each first-touch triggers a full copy-up. Framed this way, the earlier database and large-log-file warnings aren’t arbitrary rules of thumb — they’re direct consequences of this one mechanism.

Network filesystem incompatibility

One more practical constraint worth flagging here: OverlayFS has long had limited, inconsistent, or outright unsupported behavior when either its lowerdir or upperdir sits on a network filesystem such as NFS. This is a direct consequence of certain filesystem features (extended attributes, consistent d_type reporting, specific locking semantics) that OverlayFS depends on but that network filesystems don’t always implement identically to a local one. Production Docker hosts are expected to keep /var/lib/docker on genuine local storage for this reason.

Storage drivers aren’t usually top-of-mind for container security, but overlay2’s behavior has direct, practical consequences.

Defense in depth beyond the storage driver

It’s worth being clear-eyed that overlay2, like any storage driver, is implemented in kernel code and has, at various points in its history, been the subject of security patches addressing specific bugs — this is true of essentially every actively developed kernel subsystem, not a special weakness unique to overlay2. The practical takeaway isn’t to distrust overlay2 specifically, but to apply the same baseline hygiene that applies to any kernel-adjacent container component: keep host kernels patched and up to date, run containers with the least privilege they actually need (avoiding unnecessary root or extra capabilities), and treat the storage driver as one layer in a broader defense-in-depth strategy rather than a security boundary on its own.

overlay2 problems tend to show up as either “disk is unexpectedly full” or “container start is unexpectedly slow.” Both have a small, predictable set of things worth watching.

Where these metrics surface in day-to-day tooling

Docker’s own disk-usage summary breaks total storage down into images, containers, local volumes, and a build-cache category, along with how much of each is “reclaimable” versus actively in use — this single view is usually the fastest way to see whether unexpected growth is coming from dangling image layers, stopped-but-not-removed containers, or genuinely active data. At a cluster level, tools like cAdvisor and the metrics it feeds into Prometheus-based monitoring stacks report per-container filesystem usage by inspecting each container’s overlay2 upperdir directly, which is how dashboards can show “container X is using Y MB of writable storage” without needing any cooperation from the application running inside that container.

Most of what separates a lean, fast-building image from a bloated, slow one comes down to how well the author worked with overlay2’s layer model instead of against it.

Good pattern: multi-stage builds

Multi-stage builds let an image use one temporary “build” stage full of compilers and build tools, then copy only the final compiled artifact into a clean final stage. Because each stage produces its own independent layer stack, the bulky build-tool layers are never part of the final image’s lowerdir chain at all — they simply never get referenced.

Good pattern: squashing intentionally, not by default

Some teams reach for image “squashing” — collapsing an entire layer stack into one — as a blanket size-reduction technique. It’s worth applying deliberately rather than reflexively: squashing throws away the very layer-sharing benefit this whole tutorial has been explaining, since a squashed image can no longer share individual layers with any other image at all. It’s a reasonable trade for a final, rarely-rebuilt distribution artifact, but a poor default for images that are rebuilt frequently or that share a common base with many siblings.

A short, practical checklist distilled from everything covered so far.

overlay2 isn’t confined to Docker Desktop toy examples — it’s the storage foundation under an enormous share of production container infrastructure.

Copy-up and whiteouts explain most of what overlay2 does day to day, but two subtler kernel features quietly fix problems the basic model would otherwise have with renamed directories and repeated copy-ups.

The renamed-directory problem

Imagine a directory named /app/old-config exists down in a lower layer, and a container renames it to /app/new-config. A naive union filesystem would be stuck: it can’t move the directory in the read-only lowerdir, and simply creating a new upperdir directory called new-config wouldn’t automatically know to “inherit” the old directory’s hidden lower-layer contents once merged. OverlayFS solves this with a feature called redirect_dir.

When a rename like this happens, overlay2 creates the new directory in upperdir and stores a special extended attribute on it — trusted.overlay.redirect — pointing back to the original path down in the lowerdir stack. When the kernel builds the merged view and encounters that attribute, it knows to keep resolving that directory’s original lower-layer contents under the new name, instead of treating it as an empty new folder.

Metadata-only copy-up

Recall from the earlier chapter that copy-up duplicates an entire file’s content into upperdir the moment any part of it is modified. Newer kernels soften this for a common special case: changes that only touch a file’s metadata — its permissions, ownership, or timestamps — rather than its actual byte content. In that situation, the kernel can perform a lightweight “metadata-only” copy-up, recording just the changed attributes without duplicating the full file data, and only falling back to a full data copy-up once the file’s content itself is actually written to.

The index feature and hard-link tracking

OverlayFS also maintains an internal index directory that tracks the relationship between an upperdir copy of a file and its original lower-layer counterpart, primarily to correctly support hard links and to detect certain classes of inconsistency across a layer stack safely. This index is entirely internal bookkeeping — you’ll see its footprint on disk, but Docker and application code never interact with it directly.

Because overlay2 is implemented as a genuine kernel filesystem rather than a block-device abstraction, it interacts with Linux memory management in ways that are worth understanding on their own.

Shared page cache across containers

When two different containers both read the same unmodified file from a shared lower layer — say, the same shared C library from an identical base-image layer — the Linux kernel’s page cache can serve both reads from the very same physical memory pages. The file is only read from disk once; every subsequent container reading that same lower-layer file benefits from the page already being cached in RAM.

Where sharing stops: after copy-up

The moment copy-up duplicates a file into a container’s upperdir, that container now has its own private copy — and its own private page-cache entry for it going forward. Ten containers that have each independently modified the same originally-shared configuration file no longer share any caching benefit for that file; each container’s writes and subsequent reads are now isolated to its own upperdir copy.

Memory accounting and cgroups

Page-cache pages backing a container’s files are generally accounted against that container’s memory cgroup when the container is what caused them to be read or written, which is part of why an image with very large files, or a container that reads a lot of data, can appear to consume more of its memory limit than its actual process heap would suggest — the kernel is counting cached file pages, not just active application memory.

Why overlay2 generally outperforms block-based drivers for read-heavy workloads

Because reads pass through the normal Linux filesystem and page-cache path, applications doing mostly reads against image content — a typical web server serving static assets baked into the image, for instance — tend to perform close to native filesystem speed. Block-based drivers like devicemapper, by contrast, introduce an extra layer of block-device indirection for every I/O operation, which is one of the reasons the ecosystem broadly moved toward overlay2 as those older drivers matured out of favor.

No. overlay2 is a Docker storage driver that sits on top of an already-formatted filesystem (typically ext4 or xfs) and uses the kernel’s OverlayFS feature to stack directories from that underlying filesystem.

Because shared base layers between images are stored exactly once on disk. The “size” reported per image includes shared layers in its total, so the numbers overlap rather than add up.

No. A whiteout only hides the file from the merged view of a running container; the original bytes remain in whichever lower (image) layer they were created in.

Most likely the database’s data directory is sitting on overlay2’s writable layer, so every modified page inside its data files triggers a whole-file copy-up the first time it’s touched. Mounting the data directory as a volume removes this overhead entirely.

Docker uses exactly one storage driver per daemon at a time; changing it typically requires re-pulling images and rebuilding containers, since the on-disk layout is driver-specific.

Yes — for any reasonably modern Linux kernel and filesystem combination, overlay2 remains the officially recommended and most widely used storage driver.

Generally no — OverlayFS has historically had limited or unreliable support for network filesystems like NFS as a lower or upper layer, so /var/lib/docker is expected to sit on a genuine local filesystem such as ext4 or xfs.

It can. Stacking overlay2 on top of overlay2 (an overlay filesystem as the lowerdir for another overlay mount) has historically been unsupported or restricted by the kernel, which is why Docker-in-Docker setups often fall back to a different storage strategy inside the nested daemon.

The folder name is a local, host-specific cache-id, while docker inspect and docker images typically display content-addressable digests (the layer’s DiffID or the distributable digest). Docker keeps an internal mapping between the two; they’re deliberately different identifiers for different purposes.

Not directly — Docker’s internal metadata database tracks which layers belong to which images and containers, and manually deleting a folder it still references can corrupt that bookkeeping. Use Docker’s own pruning commands, which safely remove only genuinely unreferenced layers.

overlay2 turns the abstract idea of a “container image” into something concrete and efficient: read-only stacked layers on disk, merged live by the kernel, with a thin writable layer capturing whatever a specific container changes. Nothing is copied until it has to be, nothing is truly deleted until the layer that created it is gone, and the entire system is built on two elegantly simple tricks — copy-up and whiteouts — repeated consistently at every level, from a single file edit to an entire multi-gigabyte image.