Skip to main content

UnionFS

UnionFS (short for union file system) is a filesystem service that allows multiple directories (called branches) to be transparently overlaid into a single unified view. Files and directories from different sources appear to coexist in one location, even though they may physically reside on separate underlying filesystems.

One of UnionFS’s key features is copy-on-write: when a file from a read-only branch is modified, it is copied to a writable branch before changes are applied. This preserves the integrity of the original source while allowing flexibility in the overlay.

History​

UnionFS was first developed in the early 2000s as a kernel module for Linux. Its primary purpose was to enable layering of filesystems in a way that simplified package management, live CDs, and embedded systems. Over time, similar concepts were integrated into the Linux kernel as overlayfs, which is now commonly used because of its performance and stability.

UnionFS itself lives on as unionfs-fuse, a FUSE (Filesystem in Userspace) implementation that makes union functionality available without requiring kernel modules. Both implementations helped shape the way modern operating systems and container platforms handle layered filesystems.

Examples of Usage​

  1. Merging Configurations Combine system defaults, vendor configurations, and administrator overrides into a single directory tree:

    /etc/myapp/conf.d (base configs, read-only)
    /opt/vendor/defaults (vendor-supplied settings, read-only)
    /srv/ops/overrides (admin overrides, read-write)

    The resulting union view shows all three as if they were in the same directory.

  2. Aggregating Logs Present logs from multiple applications and containers under one unified directory for easy searching and analysis.

  3. Scratch Layers for Users Give a user a writable overlay on top of a read-only home directory image, so experiments and changes don’t affect the base environment.

Relation to Containerization​

Union-style filesystems directly influenced modern container technologies such as Docker, Podman, and Kubernetes. Containers rely on layering images:

  • Base layer: operating system files
  • Additional layers: application dependencies and runtime libraries
  • Writable layer: the container’s live state

OverlayFS (inspired by UnionFS) is widely used under the hood to implement this layered approach. Without union-style filesystems, containers would be far less efficient, as each container would need a full copy of its filesystem rather than sharing common base layers.

Conclusion​

UnionFS introduced the idea of unifying multiple directory trees into one view, enabling flexibility in how filesystems are managed and presented. Its design solved real-world problems for system administration, live media, and embedded environments. Today, its legacy lives on in OverlayFS and container platforms, where layered filesystems are a foundational concept.

UnionFS remains a valuable tool for learning, experimentation, and use cases where its flexible user-space overlay behavior provides benefits beyond kernel-level alternatives.