8.1.2.2 Runtime Writable Overlay
A focused guide to Runtime Writable Overlay, connecting core concepts with practical Docker and container operations.
The runtime writable overlay is the topmost layer in a running container's union filesystem, sitting above all of the underlying image's read-only layers, providing the actual location where all of that specific container's filesystem writes are recorded.
How the Overlay Fits Into the Layered Structure
The storage driver (commonly overlay2 on modern Linux systems) presents the writable layer as the topmost, authoritative layer for any path that has been modified, falling back to the appropriate underlying read-only layer for anything that hasn't.
docker run -d --name myapp myapp:1.0
docker inspect myapp --format '{{.GraphDriver.Data.UpperDir}}'
This reveals the actual host filesystem location backing the container's writable overlay — the "upper" layer in overlay2 terminology.
Why the Overlay Mechanism Enables Efficient Layering
The overlay filesystem mechanism allows the writable layer to be combined with the underlying read-only layers without needing to physically duplicate any of that read-only content, providing both the unified view applications expect and the storage efficiency Docker's layered approach depends on.
docker inspect myapp --format '{{.GraphDriver.Data.LowerDir}}'
This reveals the underlying read-only layers this container's writable overlay is layered on top of.
Observing the Overlay's Actual Disk Usage
The writable overlay's actual disk usage reflects only the changes specific to this container, rather than the full size of the entire merged filesystem view.
docker ps -s --filter name=myapp
The reported size here specifically reflects this container's own writable overlay content, distinct from the (potentially much larger) underlying shared image layers.
Why Understanding the Runtime Writable Overlay Matters
A clear grasp of how the writable overlay sits atop the image's read-only layers, and how the union filesystem mechanism combines them into a single coherent view, is foundational to understanding both how containers achieve isolated, independent filesystem state and how Docker manages to do so efficiently across many containers sharing common underlying content.