This document details the individual storage driver implementations in Docker's graph driver subsystem. Each driver provides a different approach to managing container and image filesystem layers using various underlying storage technologies.
Docker supports multiple storage drivers, each optimized for different use cases and underlying filesystems. The choice of storage driver affects performance, space efficiency, and compatibility with different environments.
For the broader graph driver architecture and interfaces, see Graph Driver Architecture. For volume management, see Volume Management.
Docker supports several storage driver implementations with platform-specific defaults and capabilities:
| Driver | Platforms | Default | Union FS | Native Diff | Quota Support |
|---|---|---|---|---|---|
overlay2 | Linux | Yes | OverlayFS | Yes | XFS Project |
fuse-overlayfs | Linux | No | FUSE-OverlayFS | No | No |
windowsfilter | Windows | Yes | Windows Filter | Yes | VHD Expansion |
btrfs | Linux | No | Btrfs Subvolumes | No | Btrfs Quotas |
zfs | Linux, FreeBSD | FreeBSD | ZFS Datasets | No | ZFS Quotas |
vfs | All | Fallback | Directory Copy | No | XFS Project |
Driver Selection Priority:
overlay2,fuse-overlayfs,btrfs,zfs,vfs daemon/graphdriver/driver_linux.go4windowsfilter daemon/graphdriver/driver_windows.go4zfs daemon/graphdriver/driver_freebsd.go4Sources: daemon/graphdriver/driver_linux.go1-4 daemon/graphdriver/driver_windows.go1-4 daemon/graphdriver/driver_freebsd.go1-4
The overlay2 driver is the default Linux storage driver, implementing efficient layered storage using the kernel's OverlayFS union filesystem.
The overlay2 driver initialization performs several prerequisite checks:
overlayutils.SupportsOverlay() daemon/graphdriver/overlay2/overlay.go142d_type support via fs.SupportsDType() daemon/graphdriver/overlay2/overlay.go155usingMetacopy() daemon/graphdriver/overlay2/overlay.go163quota.NewControl() daemon/graphdriver/overlay2/overlay.go191Sources: daemon/graphdriver/overlay2/overlay.go91-104 daemon/graphdriver/overlay2/overlay.go127-210 daemon/graphdriver/overlayutils/overlayutils.go40-80
Key components:
diff/: Contains the actual layer content changes daemon/graphdriver/overlay2/overlay.go50work/: Required by OverlayFS for atomic operations daemon/graphdriver/overlay2/overlay.go55merged/: Mount point where the unified view is accessible daemon/graphdriver/overlay2/overlay.go54lower: File containing colon-separated list of lower layers daemon/graphdriver/overlay2/overlay.go52link: Contains a short unique identifier for the layer daemon/graphdriver/overlay2/overlay.go57l/: Directory with symbolic links using short IDs to avoid path length limits daemon/graphdriver/overlay2/overlay.go58Sources: daemon/graphdriver/overlay2/overlay.go48-68 daemon/graphdriver/overlay2/overlay.go69-86
| Feature | Purpose | Implementation |
|---|---|---|
| Short link IDs | Avoid command line length limits | idLength = 26 chars, symlinks in l/ daemon/graphdriver/overlay2/overlay.go85 |
| Mount reference counting | Avoid redundant mounts | mountref.Counter daemon/graphdriver/overlay2/overlay.go97 |
| Native diff operations | Efficient layer diffs | Check via doesSupportNativeDiff() daemon/graphdriver/overlay2/check.go28 |
| Metacopy detection | Optimize metadata operations | usingMetacopy() daemon/graphdriver/overlay2/check.go143 |
| Index parameter | Control overlay index | Detect /sys/module/overlay/parameters/index daemon/graphdriver/overlay2/overlay.go202 |
Sources: daemon/graphdriver/overlay2/overlay.go69-104 daemon/graphdriver/overlay2/check.go28-125 daemon/graphdriver/overlay2/check.go143-205
The fuse-overlayfs driver provides OverlayFS capabilities implemented in userspace via FUSE, enabling container layers in unprivileged user namespaces or kernels lacking native overlay support in user namespaces.
The driver checks for the fuse-overlayfs binary in $PATH and requires at least kernel version 4.18.0 daemon/graphdriver/fuse-overlayfs/fuseoverlayfs.go77 It mounts filesystems detected via fstype.FsMagicFUSE daemon/graphdriver/fuse-overlayfs/fuseoverlayfs.go108
Sources: daemon/graphdriver/fuse-overlayfs/fuseoverlayfs.go59-104
The windowsfilter driver provides Windows container layer management using the Windows Host Compute Service (HCS) APIs.
The Windows driver uses the hcsshim package to interface with Windows container APIs. It initializes with InitFilter daemon/graphdriver/windows/windows.go92 and disallows ReFS backing volumes daemon/graphdriver/windows/windows.go99
Sources: daemon/graphdriver/windows/windows.go79-90 daemon/graphdriver/windows/windows.go92-133
The Windows driver distinguishes between read-only layers (Create) and writable containers (CreateReadWrite):
Create: Calls hcsshim.CreateLayer daemon/graphdriver/windows/windows.go212CreateReadWrite: Calls hcsshim.CreateSandboxLayer daemon/graphdriver/windows/windows.go221hcsshim.ExpandSandboxSize to set container size daemon/graphdriver/windows/windows.go237Sources: daemon/graphdriver/windows/windows.go169-241
The btrfs driver leverages Btrfs subvolumes and snapshots to provide efficient copy-on-write layer storage.
The Btrfs driver uses CGO to call Btrfs ioctls directly. It requires kernel headers >= 4.12 daemon/graphdriver/btrfs/btrfs.go11 and verifies that the backing filesystem magic matches fstype.FsMagicBtrfs daemon/graphdriver/btrfs/btrfs.go76
Sources: daemon/graphdriver/btrfs/btrfs.go11-22 daemon/graphdriver/btrfs/btrfs.go71-78 daemon/graphdriver/btrfs/btrfs.go139-146 daemon/graphdriver/btrfs/btrfs.go199-245
The zfs driver uses ZFS datasets and clones for layer storage.
ZFS driver initialization checks for the zfs executable in the system path daemon/graphdriver/zfs/zfs.go54 and checks read-write access to /dev/zfs daemon/graphdriver/zfs/zfs.go59
Sources: daemon/graphdriver/zfs/zfs.go49-122 daemon/graphdriver/zfs/zfs.go176-184 daemon/graphdriver/zfs/zfs.go237-257
The vfs driver provides a simple directory-based implementation without union filesystem support.
The VFS driver implements graphdriver.ProtoDriver daemon/graphdriver/vfs/driver.go64 It creates layers by recursively copying the parent directory into the new layer directory daemon/graphdriver/vfs/driver.go196
Create: Creates a directory and copies parent content daemon/graphdriver/vfs/driver.go160Remove: Uses containerfs.EnsureRemoveAll daemon/graphdriver/vfs/driver.go205Get: Returns the absolute path to the layer directory daemon/graphdriver/vfs/driver.go209Sources: daemon/graphdriver/vfs/driver.go33-69 daemon/graphdriver/vfs/driver.go168-197 daemon/graphdriver/vfs/driver.go204-230
The contrib/check-config.sh script is the authoritative source for kernel requirements:
| Component | Kernel Config Flag | Requirement |
|---|---|---|
| Namespaces | CONFIG_NAMESPACES, CONFIG_NET_NS, CONFIG_PID_NS | Mandatory |
| Cgroups | CONFIG_CGROUPS, CONFIG_MEMCG, CONFIG_CPUSETS | Mandatory |
| Overlay2 | CONFIG_OVERLAY_FS | Recommended |
| Btrfs | CONFIG_BTRFS_FS | For btrfs driver |
| Network | CONFIG_VETH, CONFIG_BRIDGE, CONFIG_IP_NF_FILTER | Mandatory |
Sources: contrib/check-config.sh213-226 contrib/check-config.sh276-300
Refresh this wiki