mergerfs: a union filesystem for pooling disks you already own

The problem mergerfs solves: one namespace over many disks

Most people accumulate disks rather than buying one large volume. Once you have three or four, every application that expects a single directory tree has to be told which disk holds what. mergerfs removes that bookkeeping. The README describes it as a FUSE-based union filesystem that logically combines numerous filesystem paths into a single mount point, and it frames the target as simplifying storage and management of files across commodity storage devices. The project's own shorthand for this is JBOFS, Just a Bunch of FileSystems.

The audience is fairly specific. The repository topics point at media serving (plex, jellyfin, kodi, subsonic) and at datahoarding, which matches the shape of the tool: files are large, written once, read many times, and the total library grows past the size of any single disk. The README also lists hard links, hard link copy-on-write, extended attributes, file attributes and POSIX ACLs as supported, which matters if your media tools rely on hardlinking between download and library directories.

What it is not is just as clearly stated. The non-features section rules out a read/write overlay on top of a read-only filesystem, file whiteout, RAID-like parity calculation, redundancy, and splitting of files across branches. Those exclusions define the product. mergerfs is a namespace and placement layer, not a storage layer.

How mergerfs merges directories and picks a branch for new files

mergerfs operates on paths, not block devices and not filesystem mounts. The README is explicit: it acts as a proxy to the underlying filesystem paths, combining the behavior of some functions and acting as a selector for others. That distinction explains most of its behavior. There is no metadata store, no journal, no separate on-disk format. The branches are ordinary directories on ordinary filesystems, and they remain readable without mergerfs.

The README's visualization is the clearest description of read behavior. Given /disk1 and /disk2 as branches, a directory listing of /merged combines the entries from both, deduplicating entries, and returns one list. Files that exist on only one branch simply appear. Files that exist on both appear once.

Creation is where the configuration lives. When a file or directory is created, a policy runs first to determine which branch is selected. Which policy applies is set through config options, and the README points at the policies documentation for the full set. This is the part worth reading before you mount anything, because the policy decides where your data physically ends up, and moving files afterward means working on the branches directly.

For operations that change attributes or remove a file, the README says the behavior may be applied to all instances found. That is the union semantics showing through: a delete or a chmod can touch every branch holding that path, not just the one you happened to see.

Installing mergerfs on Ubuntu or Debian and making a first mount

The README does not include install commands. It links to a QuickStart page at https://trapexit.github.io/mergerfs/latest/quickstart/ and to the full documentation at https://trapexit.github.io/mergerfs, and those are the sources to follow for your distribution. The repository does ship packaging material: there is a debian/ directory, a mergerfs.spec for RPM-based systems, and a Makefile whose default target is debian:13.amd64. The Makefile's own default target line is the build entry point:

DEFAULT_TARGET := debian:13.amd64

That is the target the Makefile selects when you run make with no arguments, so a source build on this repository starts from there. On Debian and Ubuntu systems, the debian/ directory is the packaging path, and the QuickStart page is where the project says to look for the install steps themselves.

The README points at the config/options and functions/categories/policies documentation for the settings a mount line takes. The path list before the mount point is a colon-separated set of existing paths, and the README states that paths of the same or different filesystems can be combined, so you are not restricted to identical disks. The option string is where policies are set. Confirm the exact names and accepted values on those documentation pages before mounting.

After mounting, the practical check is that the merged view reflects both branches. Create a file in the mount point and then look at the branch directories directly to see which one the policy chose. Because mergerfs is runtime configurable through its runtime interface, you can change settings on a live mount rather than unmounting, which is useful when you are still deciding on a create policy.

Adding or removing a branch later does not require touching the data on the remaining disks. The README lists that as a feature: filesystems and paths can be added or removed without impacting the rest of the data. That is the operational payoff of keeping branches as plain directories.

Where mergerfs is the wrong tool

The README's non-features list is unusually direct, and it should be read as a set of disqualifiers. There is no redundancy and no RAID-like parity calculation. If a branch disk dies, the files that lived on it are gone; mergerfs has no mechanism to reconstruct them. The README points readers to SnapRAID for parity, which is a separate tool with a separate operational model.

Files are not split across branches. A single file lives on one branch, so a file larger than the largest branch cannot be stored. This is the opposite of a pooled block device, and it is a hard boundary rather than a tuning problem.

There is no file whiteout and no read/write overlay on top of a read-only filesystem. If you want a writable layer over an immutable base image, the README says that is OverlayFS territory, and it is right to draw the line there.

The README also states that mergerfs is unaffected by individual filesystem failure, which is true only in the narrow sense that the mount and the surviving branches keep working. It does not mean your data survives. Anyone reading that line as a durability claim is reading it wrong, and the non-features list is where that gets corrected.

mergerfs compared with ZFS and RAID-style pooling

The comparison that matters most is against ZFS. ZFS is a combined volume manager and filesystem: it creates the pool, owns the on-disk format, computes checksums, and can rebuild a failed disk from parity or mirrors. mergerfs does none of that. It takes paths that already exist on filesystems you created with mkfs and presents them as one directory tree. You cannot add a disk to a ZFS pool and have it rebalance existing data the way you can add a branch to a mergerfs mount, because mergerfs has no data to rebalance; the files never moved.

The trade-off runs both ways. ZFS gives you integrity checking and recovery, at the cost of a format you cannot read without ZFS and a pool whose geometry you must plan. mergerfs gives you branches you can pull out and mount anywhere, at the cost of any protection at all. The README's own comparison page places mergerfs alongside mhddfs, unionfs, aufs and DrivePool, which is the correct peer group: all of them are union layers, not storage engines.

Against a plain RAID array the difference is simpler. RAID stripes or mirrors at the block level and hides individual disks. mergerfs does not stripe and does not mirror. You see the disks, you choose where files go, and you accept that a dead disk means dead files.

Maintenance, licensing and what upgrades cost you

The repository is not archived, and the last push was on 2026-09-21. Releases are infrequent and deliberate: 2.42.0 on 2026-05-08, 2.41.1 on 2025-11-19 and 2.41.0 on 2025-11-12. That cadence suggests a project that ships when there is something to ship rather than on a schedule.

Upgrades are cheap in one respect and not in another. mergerfs stores no data of its own, so replacing the binary does not migrate anything; your branches are untouched. What changes between versions is behavior, and the README directs configuration through options and policies, so a policy default that shifts between releases can change where new files land. Read the release notes before upgrading a production mount.

On licensing, the README states the software is released under the ISC license and describes it as very liberal, free for personal or commercial use. That is the project's own characterization, not legal advice; if you are embedding mergerfs in a product, read the LICENSE file in the repository and get your own counsel. The README also asks commercial users to consider sponsoring, which is a funding request rather than a license term.

Support is documented at https://trapexit.github.io/mergerfs/latest/support/, and the README notes that custom features can be discussed directly with the maintainer. That is a realistic picture of a small, single-maintainer project: good documentation, slow release cadence, and no commercial support contract behind it.

Editorial conclusion

mergerfs suits people consolidating several commodity disks into one namespace, especially media servers where files are large, mostly written once and rarely rewritten. It does not suit anyone who needs redundancy, parity or file splitting across devices; the README lists all three as non-features, and points at SnapRAID for parity instead. Before committing data, verify the branch paths in your mount line, confirm the policy that governs create placement, and check that the filesystem types you intend to use appear in the compatibility list. A mergerfs mount is a view over paths that already exist, so a wrong policy scatters new files across disks in ways that are tedious to undo.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. trapexit/mergerfs on GitHub