explaingit

trapexit/mergerfs

5,627C++Audience · ops devopsComplexity · 3/5LicenseSetup · moderate

TLDR

A Linux tool that combines multiple storage drives or folders into a single merged directory, so all your files appear in one place without special hardware.

Mindmap

mindmap
  root((mergerfs))
    What it does
      Pools multiple drives
      Single directory view
      Transparent file lookup
    Storage policies
      Fill drives in order
      Spread files evenly
      Custom rules
    Tech Stack
      C++
      Linux FUSE
      ISC license
    Use Cases
      Media library pooling
      Home NAS setup
      Archive management
    Companion tools
      SnapRAID for parity
      Jellyfin media server
      Kodi
Click or tap to explore — scroll the page freely

Code map

Detail Auto

An interactive map of this repo's files and how they connect — its source is parsed live in your browser. Click Visualize to build it.

filefunction / class

Things people build with this

USE CASE 1

Pool several external hard drives into one directory so a media server like Jellyfin sees your entire movie library in one place.

USE CASE 2

Add a new drive to your home NAS storage pool without moving or reorganizing existing files on other drives.

USE CASE 3

Configure a fill-one-at-a-time policy so mergerfs packs each drive before starting the next, maximizing usable space.

USE CASE 4

Combine multiple folders on the same drive into a unified namespace for a home archive without copying data.

Tech stack

C++FUSELinux

Getting it running

Difficulty · moderate Time to first run · 30min

Requires Linux with FUSE support, pool configuration is done via fstab or command line, and each drive must be separately mounted first.

ISC license: use freely for personal or commercial purposes with minimal restrictions.

In plain English

mergerfs is a tool that lets you combine multiple storage drives or folders into one single location, so that files spread across many disks appear to be in one place. You do not need special hardware or a RAID controller. You just point mergerfs at several folders, and it presents them together as if they were one folder on your computer. The main use case is for people who collect large amounts of data, such as movie libraries or file archives, and have acquired several drives over time. Instead of keeping track of which file is on which drive, mergerfs shows everything in one directory tree. You can add a new drive or remove an old one without disrupting the rest of your data. When you copy a new file into the merged folder, mergerfs runs a policy to decide which underlying drive should actually store it. You can configure these policies to fill drives one at a time, spread files out evenly, or follow other rules. When you read a file, mergerfs looks across all the drives to find it and returns it transparently. The tool also supports extended file attributes, access control lists, and other standard filesystem features, so most software that reads and writes files will work with it without changes. mergerfs does not provide redundancy or parity, so if a drive fails, the files on that drive are lost. It is not a replacement for backups or for systems like RAID that mirror data. The README points to SnapRAID as a companion tool if parity protection is needed. mergerfs is focused purely on pooling storage and making it accessible in one place, with good performance through a passthrough mode that avoids unnecessary overhead. The software is written in C++ and released under the ISC license, which allows personal and commercial use. It is developed by a single maintainer and widely used with media server software such as Jellyfin and Kodi.

Copy-paste prompts

Prompt 1
Set up mergerfs on Ubuntu to combine three external drives at /mnt/disk1, /mnt/disk2, /mnt/disk3 into a single pool at /mnt/pool, using a fill-one-drive-first policy.
Prompt 2
Explain the difference between mergerfs storage policies mfs, eplfs, and ff, and help me pick the right one for a Jellyfin media server with 4 drives of different sizes.
Prompt 3
Show me how to add a new 8TB drive to an existing mergerfs pool without disrupting files already on the other drives.
Prompt 4
Set up mergerfs alongside SnapRAID so I get a unified storage pool with parity protection against a single drive failure.
Open on GitHub → Explain another repo

← trapexit on gitmyhub — every repo by this author, as a profile.

Verify against the repo before relying on details.