# trapexit/mergerfs

**Attribution required: if you use, quote, or summarise this content, you must credit and link back to [awesome-repositories.com](https://awesome-repositories.com/repository/trapexit-mergerfs).**

_How this analysis was created: the description and tags below were written by an AI model that read this project's README and public documentation pages; stars, license and language come straight from the GitHub API. The model does not read the source code._

5,709 stars · 218 forks · C++ · NOASSERTION

## Links

- GitHub: https://github.com/trapexit/mergerfs
- Homepage: http://trapexit.github.io/mergerfs/
- awesome-repositories: https://awesome-repositories.com/repository/trapexit-mergerfs.md

## Topics

`aufs` `datahoarding` `filesystem` `fuse` `jbod` `jbofs` `jellyfin` `kodi` `libfuse` `mergerfs` `mhddfs` `overlayfs` `plex` `subsonic` `unionfs` `xattr`

## Description

mergerfs is a FUSE-based union filesystem that pools multiple independent filesystems or directories into a single unified mount point. It acts as a proxy to underlying storage, forwarding file operations directly to the filesystem for near-native performance while merging directory listings and attribute changes. The project provides a live, read-write pooled view of storage that aggregates drives of any size without requiring reformatting or data redistribution, and it isolates individual drive failures so that the pool continues serving data from remaining filesystems.

The filesystem offers policy-driven file placement, selecting which underlying branch stores new files based on configurable rules such as free space thresholds or path existence. It supports copy-on-write behavior by duplicating files on write operations when hard links are broken or cross-device renames occur, and it can automatically relocate files to another branch when a write fails due to insufficient space. Dynamic branch list management allows storage paths to be added, removed, or reordered at runtime without disrupting the pool, and an extended attribute command interface enables runtime configuration changes and action triggering through special attribute keys on a pseudo file.

Beyond its core pooling and placement capabilities, mergerfs provides direct I/O passthrough that bypasses the FUSE layer for near-native read and write performance, along with configurable file caching and page cache management. It includes tools for monitoring filesystem metadata, forwarding change events, and benchmarking read and write performance through null operations. The project also offers user and group ID mapping for container environments, POSIX permission enforcement, and integration with external redundancy tools like SnapRAID for parity protection. Configuration is handled through command-line parameters, configuration files, or runtime attribute manipulation, and the filesystem can be set to mount automatically at boot via fstab or managed as a systemd service.

## Tags

### DevOps & Infrastructure

- [Union Filesystem Mounting](https://awesome-repositories.com/f/devops-infrastructure/layered-filesystems/union-filesystem-mounting.md) — Combines multiple filesystems or directories into a single unified mount point, acting as a proxy to underlying storage. ([source](https://trapexit.github.io/mergerfs/latest/))
- [Container User Identity Mapping](https://awesome-repositories.com/f/devops-infrastructure/container-deployment/container-user-identity-mapping.md) — Maps container user and group identifiers to host-level IDs for correct file ownership on the union filesystem. ([source](https://trapexit.github.io/mergerfs/latest/faq/compatibility_and_integration/))
- [Runtime Configurations](https://awesome-repositories.com/f/devops-infrastructure/storage-backend-configurations/runtime-configurations.md) — Changes filesystem options and triggers commands at runtime through extended attribute calls on a pseudo file. ([source](https://trapexit.github.io/mergerfs/latest/runtime_interface/))
- [Storage Branch Constraint Filters](https://awesome-repositories.com/f/devops-infrastructure/version-control-management/version-control-workflows/branch-based-isolation/branch-filters/storage-branch-constraint-filters.md) — Excludes branches that are read-only, lack free space, or are in a no-create mode before file placement. ([source](https://trapexit.github.io/mergerfs/latest/config/functions_categories_policies/))
- [User Permission Mapping](https://awesome-repositories.com/f/devops-infrastructure/volume-mounts/host-guest-mounts/user-permission-mapping.md) — Passes host-level UID/GID values from user namespaces to the union mount for container permission bridging. ([source](https://trapexit.github.io/mergerfs/latest/faq/compatibility_and_integration/))

### Operating Systems & Systems Programming

- [FUSE-Based Filesystem Mounts](https://awesome-repositories.com/f/operating-systems-systems-programming/filesystem-mounting/fuse-based-filesystem-mounts.md) — Forwards filesystem operations to underlying storage through a FUSE layer, enabling near-native performance and POSIX compatibility.
- [Direct I/O Access](https://awesome-repositories.com/f/operating-systems-systems-programming/direct-i-o-access.md) — Bypasses the FUSE layer to perform reads and writes directly on the underlying filesystem for near-native performance.
- [FUSE Layer Bypass for File I/O](https://awesome-repositories.com/f/operating-systems-systems-programming/direct-i-o-access/fuse-layer-bypass-for-file-i-o.md) — Bypasses the FUSE union layer to perform file I/O directly on underlying filesystems for near-native performance. ([source](https://trapexit.github.io/mergerfs/latest/config/passthrough/))
- [Filesystem Operation Proxies](https://awesome-repositories.com/f/operating-systems-systems-programming/file-i-o-management/i-o-polling/file-and-console-i-o/filesystem-operation-proxies.md) — Passes file I/O directly to underlying filesystems for near-native performance while merging directory listings. ([source](https://cdn.jsdelivr.net/gh/trapexit/mergerfs@master/README.md))
- [Union Mount Configurations](https://awesome-repositories.com/f/operating-systems-systems-programming/filesystem-mounting/fuse-based-filesystem-mounts/union-mount-configurations.md) — Configures a FUSE-based union mount with command-line options, config files, and runtime controls.
- [Local and Remote Mount Pooling](https://awesome-repositories.com/f/operating-systems-systems-programming/filesystem-mounting/remote-repository-mounts/local-and-remote-mount-pooling.md) — Unifies locally attached filesystems with remote mounts under a single pool directory. ([source](https://trapexit.github.io/mergerfs/latest/project_comparisons/))
- [Dynamic Filesystem Attachments and Detachments](https://awesome-repositories.com/f/operating-systems-systems-programming/root-filesystem-detachments/dynamic-filesystem-attachments-and-detachments.md) — Dynamically attaches or detaches filesystem paths from the pool without disrupting existing data. ([source](https://cdn.jsdelivr.net/gh/trapexit/mergerfs@master/README.md))
- [Copy-on-Write Filesystems](https://awesome-repositories.com/f/operating-systems-systems-programming/virtualization-emulation/virtualization-platforms/virtualization-architectures/copy-on-write-disk-formats/copy-on-write-filesystems.md) — Provides copy-on-write behavior by breaking hard links and duplicating files on write operations.
- [Filesystem Operation Categorizations](https://awesome-repositories.com/f/operating-systems-systems-programming/filesystem-operations/filesystem-operation-categorizations.md) — Groups POSIX filesystem functions into action, create, and search categories for unified policy assignment. ([source](https://trapexit.github.io/mergerfs/latest/config/functions_categories_policies/))
- [Extended File Attributes](https://awesome-repositories.com/f/operating-systems-systems-programming/system-administration-maintenance/file-system-management/file-system-utilities/file-metadata-inspection/metadata-preservation-engines/metadata-extraction/file-system-attributes/extended-file-attributes.md) — Passes through extended attributes, file attributes, and POSIX ACLs to the underlying filesystem. ([source](https://trapexit.github.io/mergerfs/latest/))
- [Command Extended Attributes](https://awesome-repositories.com/f/operating-systems-systems-programming/system-administration-maintenance/file-system-management/file-system-utilities/file-metadata-inspection/metadata-preservation-engines/metadata-extraction/file-system-attributes/extended-file-attributes/command-extended-attributes.md) — Ships an extended attribute command interface for runtime configuration changes and action triggering.
- [Path Existence Branch Restrictions](https://awesome-repositories.com/f/operating-systems-systems-programming/system-administration-maintenance/file-system-management/file-system-utilities/path-validation-utilities/path-existence-assurance/path-existence-branch-restrictions.md) — Restricts branch selection to those where the target relative path already exists. ([source](https://trapexit.github.io/mergerfs/latest/config/functions_categories_policies/))
- [Copy-on-Write File Copies](https://awesome-repositories.com/f/operating-systems-systems-programming/virtualization-emulation/virtualization-platforms/virtualization-architectures/copy-on-write-disk-formats/copy-on-write-filesystems/copy-on-write-file-copies.md) — Creates new files that share storage with the original until one is modified, saving disk space. ([source](https://trapexit.github.io/mergerfs/latest/config/link_cow/))
- [Copy-on-Write File Duplications](https://awesome-repositories.com/f/operating-systems-systems-programming/virtualization-emulation/virtualization-platforms/virtualization-architectures/copy-on-write-disk-formats/copy-on-write-filesystems/copy-on-write-file-duplications.md) — Duplicates files on write to preserve separate identities when hard links are broken or cross-device renames occur.
- [Hard Link Break Copies](https://awesome-repositories.com/f/operating-systems-systems-programming/virtualization-emulation/virtualization-platforms/virtualization-architectures/copy-on-write-disk-formats/copy-on-write-filesystems/hard-link-break-copies.md) — Implements copy-on-write behavior by breaking hard links and duplicating files on write operations.
- [Hard Link Copy-on-Write](https://awesome-repositories.com/f/operating-systems-systems-programming/virtualization-emulation/virtualization-platforms/virtualization-architectures/copy-on-write-disk-formats/copy-on-write-filesystems/hard-link-copy-on-write.md) — Creates a copy of a hardlinked file before modifying it, preserving the original link and saving space. ([source](https://trapexit.github.io/mergerfs/latest/config/options))

### Part of an Awesome List

- [Filesystem](https://awesome-repositories.com/f/awesome-lists/devops/actor-frameworks/placement-policies/filesystem.md) — Provides policy-driven file placement selecting which underlying branch stores new files based on configurable rules.

### Data & Databases

- [Storage Branch Selection Policies](https://awesome-repositories.com/f/data-databases/data-engineering-infrastructure/backup-and-recovery-utilities/backup-selection-policies/storage-branch-selection-policies.md) — Selects a storage branch for filesystem operations using algorithms that consider space, path existence, or randomness. ([source](https://trapexit.github.io/mergerfs/latest/config/functions_categories_policies/))
- [Incremental Drive Additions](https://awesome-repositories.com/f/data-databases/data-modification-apis/incremental-syncing/incremental-data-merging/incremental-drive-additions.md) — Expands the storage pool by adding new filesystems at any time without reformatting or redistributing existing data. ([source](https://trapexit.github.io/mergerfs/latest/project_comparisons/))
- [Writable Pooled Views](https://awesome-repositories.com/f/data-databases/database-management-systems/database-systems-management/performance-optimization-tools/write-ahead-logging-configurations/read-only-isolate-pooling/writable-pooled-views.md) — Provides a live, writable, always-updated filesystem view of the pooled storage. ([source](https://trapexit.github.io/mergerfs/latest/project_comparisons/))
- [Filesystem Freeze Blocking](https://awesome-repositories.com/f/data-databases/distributed-filesystems/filesystem-synchronization/filesystem-freeze-blocking.md) — Implements synchronous POSIX call behavior that halts all threads when an underlying branch filesystem blocks. ([source](https://trapexit.github.io/mergerfs/latest/faq/technical_behavior_and_limitations/))
- [Fault Tolerant Storage](https://awesome-repositories.com/f/data-databases/fault-tolerant-storage.md) — Continues serving the pool and remaining data when an individual underlying filesystem becomes unavailable.
- [Storage Pool Managers](https://awesome-repositories.com/f/data-databases/fault-tolerant-storage/storage-pool-managers.md) — Aggregates drives of any size into a single writable pool without reformatting or redistributing data.
- [Runtime Branch List Managers](https://awesome-repositories.com/f/data-databases/fault-tolerant-storage/storage-pool-managers/runtime-branch-list-managers.md) — Dynamically adds, removes, or reorders storage paths in the pool at runtime without disruption.
- [Filesystem Agnostic Compatibilities](https://awesome-repositories.com/f/data-databases/storage-abstraction/local-filesystem-storage/browser-filesystem-storage/filesystem-agnostic-compatibilities.md) — Works at the filesystem level, compatible with any physical storage device without special configuration. ([source](https://trapexit.github.io/mergerfs/latest/faq/compatibility_and_integration/))
- [Automatic Write Relocations](https://awesome-repositories.com/f/data-databases/data-engineering-infrastructure/data-persistence-storage/data-storage/file-based-storage/local-file-storage/local-file-writing/binary-file-writing/automatic-write-relocations.md) — Automatically relocates files to another branch when a write fails due to insufficient space. ([source](https://trapexit.github.io/mergerfs/latest/config/options))
- [Minimum Free Space Thresholds](https://awesome-repositories.com/f/data-databases/schema-enforcement-tools/validation-constraints/minimum-size-enforcements/minimum-free-space-thresholds.md) — Specifies the minimum available space a branch must have to be considered for new file creation. ([source](https://trapexit.github.io/mergerfs/latest/config/options))
- [Direct Underlying Filesystem Accesses](https://awesome-repositories.com/f/data-databases/virtual-disk-file-access/direct-underlying-filesystem-accesses.md) — Allows reading and writing files directly on underlying filesystems for independent recovery or inspection. ([source](https://trapexit.github.io/mergerfs))

### Development Tools & Productivity

- [Storage Path Listings](https://awesome-repositories.com/f/development-tools-productivity/branch-management/local-branch-listings/storage-path-listings.md) — Provides dynamic branch list management for adding, removing, or reordering storage paths at runtime.
- [Storage Branch Listings](https://awesome-repositories.com/f/development-tools-productivity/branch-management/storage-branch-listings.md) — Manages a dynamic list of storage paths that can be added, removed, or reordered at runtime without disrupting the pool.
- [Dynamic List Manipulations](https://awesome-repositories.com/f/development-tools-productivity/branch-management/storage-branch-listings/dynamic-list-manipulations.md) — Dynamically adds, removes, prepends, or appends storage branches to the union using simple list manipulation instructions. ([source](https://trapexit.github.io/mergerfs/latest/runtime_interface/))
- [Extended Attribute Branch Manipulations](https://awesome-repositories.com/f/development-tools-productivity/branch-management/extended-attribute-branch-manipulations.md) — Dynamically adds, removes, or replaces storage branches in the union by writing to a branch extended attribute. ([source](https://trapexit.github.io/mergerfs/latest/runtime_interface/))
- [Command-Line Configurations](https://awesome-repositories.com/f/development-tools-productivity/command-line-configurations.md) — Sets branch paths and mount options directly in the terminal when starting the union filesystem. ([source](https://trapexit.github.io/mergerfs/latest/quickstart/))
- [Cross-Filesystem Rename Copies](https://awesome-repositories.com/f/development-tools-productivity/file-system-operations/cross-system-file-copying/cross-filesystem-rename-copies.md) — Copies file data and metadata between branches when a rename fails due to cross-device limitations. ([source](https://trapexit.github.io/mergerfs/latest/faq/technical_behavior_and_limitations/))
- [Union Filesystem Config Files](https://awesome-repositories.com/f/development-tools-productivity/project-configuration/automated-config-generation/cli-config-file-readers/union-filesystem-config-files.md) — Defines storage paths and mount point settings in a configuration file using key-value pairs or colon-delimited lists. ([source](https://trapexit.github.io/mergerfs/latest/config/options))

### Software Engineering & Architecture

- [Mixed-Capacity Drive Pools](https://awesome-repositories.com/f/software-engineering-architecture/keyed-resource-pools/fixed-size-pools/mixed-capacity-drive-pools.md) — Aggregates drives of any size into a single writable pool without reformatting. ([source](https://trapexit.github.io/mergerfs/latest/project_comparisons/))
- [User Namespace Mappings](https://awesome-repositories.com/f/software-engineering-architecture/execution-control/namespace-isolation/user-namespace-mappings.md) — Translates user and group identifiers between namespaces for correct file ownership in container environments. ([source](https://trapexit.github.io/mergerfs/latest/faq/technical_behavior_and_limitations/))

### Testing & Quality Assurance

- [Filesystem Failure Isolations](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-isolation/service-isolation-utilities/failure-isolation-mechanisms/filesystem-failure-isolations.md) — Isolates individual drive failures so the pool continues serving data from remaining filesystems. ([source](https://cdn.jsdelivr.net/gh/trapexit/mergerfs@master/README.md))
- [Pool Failure Isolations](https://awesome-repositories.com/f/testing-quality-assurance/general-testing-utilities/test-isolation/service-isolation-utilities/failure-isolation-mechanisms/pool-failure-isolations.md) — Isolates individual drive failures so the pool continues serving data from remaining filesystems.

### Security & Cryptography

- [POSIX Permission Enforcement](https://awesome-repositories.com/f/security-cryptography/permissive-file-permission-detection/posix-permission-enforcement.md) — Enforces POSIX file permissions by leveraging kernel default_permissions and adjusting process credentials. ([source](https://trapexit.github.io/mergerfs/latest/faq/technical_behavior_and_limitations/))
- [Kernel-Side Permission Handling](https://awesome-repositories.com/f/security-cryptography/user-access-management/file-and-folder-permissions/kernel-side-permission-handling.md) — Enforces file permissions using kernel-side checks with root-level UID/GID management for container support. ([source](https://trapexit.github.io/mergerfs/latest/faq/technical_behavior_and_limitations/))