How to Expand Jellyfin Storage with mergerfs on Proxmox LXC
As your Jellyfin movie, TV show, and music collection grows, managing multiple HDDs as separate libraries can become inconvenient. A simple solution is to use mergerfs.
mergerfs combines multiple disks into one logical storage pool. Files remain stored on their original physical disks, while Jellyfin sees a single media directory.
mergerfs does not require all disks to use the same filesystem or connection type. USB, SATA, and other Linux-mounted storage can be combined in the same pool.
This article answer the idea on previous article when I am thinking to do storage expansion after successfully setting up a Jellyfin service on a LXC container.
This example starts with:
:::codeBoth disks already contain media files, so there is no need to reformat them.
In this guide, mergerfs runs directly on the Proxmox host, while Jellyfin runs inside an LXC container.
Example Storage Layout
The existing USB disks contain the following media:
:::code Disk 1 - USB / NTFS ├── music/ │ └── The Beatles/ │ ├── Let It Be/ │ └── Past Masters/ │ └── series/ └── Alien Earth (2025)/ └── Season 01/ Disk 2 - USB / exFAT ├── music/ │ └── The Beatles/ │ └── With The Beatles/ │ └── movies/ ├── Catch Me If You Can (2002)/ └── Duck Duck Goose (2018)/ :::After mergerfs combines both disks, Jellyfin will see:
:::code
/media/
├── movies/
│ ├── Catch Me If You Can (2002)_1080p_Bluray/
│ └── Duck Duck Goose (2018) [BluRay] [720p]/
│
├── music/
│ └── The Beatles/
│ ├── Let It Be/
│ ├── Past Masters/
│ │ ├── Past Masters, Volume One/
│ │ └── Past Masters, Volume Two/
│ └── With The Beatles/
│
└── series/
└── Alien Earth (2025)/
└── Season 1/
:::
The physical files remain on their respective disks. mergerfs only presents them as one logical directory.
1. Install mergerfs on Proxmox
Install mergerfs directly on the Proxmox host.
:::code apt update apt install -y mergerfs mergerfs -V :::2. Identify the Storage Disks
Check disk names, filesystem types, UUIDs, labels, models, and mount points.
:::code
Always use UUIDs for permanent mounts instead of device names such as /dev/sdb or /dev/sdc, because device names may change after a reboot.
3. Create USB Disk Mount Points
:::codeImportant: I already have /mnt/media created. If "/mnt/media" already contains existing media files, move those files to one of the physical storage disks before mounting mergerfs on "/mnt/media". Once mergerfs is mounted, it becomes the top-level filesystem for that mount point, so the original files underneath "/mnt/media" will be hidden while the mergerfs mount is active. The files are not deleted, but they will remain inaccessible until mergerfs is unmounted.
For this reason, keep the actual media files on physical disks such as "/mnt/hdd/usbdisk01" or "/mnt/hdd/usbdisk02", and use "/mnt/media" only as the logical mergerfs mount point.
The initial layout will be:
:::code4. Mount the NTFS and exFAT Disks Permanently
Edit /etc/fstab.
Add both disks using their actual UUIDs.
:::code UUID=UUID-DISK-1 /mnt/hdd/usbdisk01 ntfs3 defaults,nofail,noatime 0 0 UUID=UUID-DISK-2 /mnt/hdd/usbdisk02 exfat defaults,nofail,noatime 0 0 :::Replace UUID-DISK-1 and UUID-DISK-2 with the actual UUID values.
Reload systemd and mount the disks.
:::code systemctl daemon-reload mount -a :::Verify both disks.
:::code findmnt /mnt/hdd/usbdisk01 findmnt /mnt/hdd/usbdisk02 df -h /mnt/hdd/usbdisk01 /mnt/hdd/usbdisk02 :::
You can also confirm the filesystem types:
:::code findmnt -o TARGET,FSTYPE,SOURCE /mnt/hdd/usbdisk01 findmnt -o TARGET,FSTYPE,SOURCE /mnt/hdd/usbdisk02 :::5. Organize the Media Folders
Each disk does not need to contain every media category.
Disk 1 is NTFS and contains music and TV series:
:::code /mnt/hdd/usbdisk01/ ├── music/ │ └── The Beatles/ │ ├── Let It Be/ │ └── Past Masters/ │ └── series/ └── Alien Earth (2025)/ └── Season 01/ :::Disk 2 is exFAT and contains music and movies:
:::code /mnt/hdd/usbdisk02/ ├── music/ │ └── The Beatles/ │ └── With The Beatles/ │ └── movies/ ├── Catch Me If You Can (2002)/ └── Duck Duck Goose (2018)/ :::Because both disks contain the same logical path:
:::code music/The Beatles/ :::mergerfs combines their contents into:
:::code /mnt/media/music/The Beatles/ ├── Let It Be/ ├── Past Masters/ └── With The Beatles/ :::Jellyfin does not need to know which physical disk contains each album.
6. Keep Folder Naming Consistent
Keep media folder names consistent across all disks.
For example:
:::code music movies series The Beatles :::Avoid inconsistent naming such as:
:::code Music music MUSIC The Beatles the beatles THE BEATLES :::Consistent naming prevents duplicate logical directories from appearing in the mergerfs pool.
7. Create the mergerfs Pool
Edit /etc/fstab again.
Add the mergerfs entry after the physical disk entries.
:::code /mnt/hdd/usbdisk* /mnt/media mergerfs defaults,allow_other,cache.files=off,category.create=pfrd,func.getattr=newest,dropcacheonclose=false,minfreespace=500M,fsname=jellyfin-media 0 0 :::
This combines:
:::code /mnt/hdd/usbdisk01 /mnt/hdd/usbdisk02 :::into:
:::code /mnt/media :::category.create=pfrd controls where new files are created, while minfreespace=500M prevents mergerfs from selecting a disk when available space falls below 500 MB.
The minfreespace could be higher for the actual practice, but again this is just a test using 2 cheap USB disk with very low capacity.
8. Mount the mergerfs Pool
:::code systemctl daemon-reload mount -a :::Verify the pool.
:::code findmnt /mnt/media df -h /mnt/media ls -lah /mnt/media :::You should see:
:::code /mnt/media/ ├── movies/ ├── music/ └── series/ :::
During the previous setup, my Jellyfin was already configured to recognize "/mnt/media" as "/media" inside the LXC container, so I won't make any additional changes.
I will simply rescan the media library and my process are stop here. The following step is only necessary if your setup differs from mine.
9. Bind mergerfs to the Jellyfin LXC
If the Jellyfin container ID is 101, stop it first.
:::code pct stop 101 :::Bind the mergerfs pool to /media inside the LXC.
Start the container again.
:::code pct start 101 :::Enter the container and verify the mount.
:::code pct enter 101 ls -lah /media :::Jellyfin should see:
:::code /media/ ├── movies/ ├── music/ └── series/ :::10. Configure Jellyfin Libraries
Open:
:::code Jellyfin Dashboard → Libraries → Add Media Library :::Use these paths:
:::code Movies /media/movies Shows /media/series Music /media/music :::Do not add individual physical disks to Jellyfin. Jellyfin should only use the merged /media directory.
11. Recommended Jellyfin Folder Structure
Movies
:::code movies/ ├── Catch Me If You Can (2002)/ │ └── Catch Me If You Can (2002).mkv │ └── Duck Duck Goose (2018)/ └── Duck Duck Goose (2018).mp4 :::TV Shows
:::code series/ └── Alien Earth (2025)/ └── Season 01/ ├── Alien Earth.S01E01.1080p.x265.mkv ├── Alien Earth.S01E02.1080p.x265.mkv └── Alien Earth.S01E03.1080p.x265.mkv :::Music
:::code music/ └── The Beatles/ ├── Let It Be/ ├── Past Masters/ │ ├── Past Masters, Volume One/ │ └── Past Masters, Volume Two/ │ └── With The Beatles/ :::12. Adding Another USB HDD
To add another USB disk, create another USB mount point.
:::code mkdir -p /mnt/hdd/usbdisk03 :::Find the UUID and filesystem:
:::code lsblk -o NAME,SIZE,FSTYPE,LABEL,UUID,MODEL,SERIAL,MOUNTPOINTS :::For example, if the new USB disk uses EXT4:
:::code UUID=UUID-DISK-3 /mnt/hdd/usbdisk03 ext4 defaults,nofail,noatime 0 2 :::Or NTFS:
:::code UUID=UUID-DISK-3 /mnt/hdd/usbdisk03 ntfs3 defaults,nofail,noatime 0 0 :::Mount the disk.
:::code systemctl daemon-reload mount /mnt/hdd/usbdisk03 findmnt /mnt/hdd/usbdisk03 :::Create only the media folders required on that disk.
:::code mkdir -p /mnt/hdd/usbdisk03/movies :::Because the mergerfs configuration already uses:
:::code /mnt/hdd/usbdisk* :::the new USB disk matches the existing branch pattern.
Remount the mergerfs pool:
:::code pct stop 101 umount /mnt/media mount /mnt/media pct start 101 :::Verify the new capacity:
:::code df -h /mnt/media findmnt /mnt/media :::13. Adding an Internal SATA Disk Later
mergerfs does not care whether a storage disk is connected through USB, SATA, or another interface. As long as the disk is mounted as a Linux directory, it can become part of the same mergerfs pool.
For example, if you later install an internal SATA HDD, create a separate mount point:
:::code mkdir -p /mnt/hdd/satadisk01 :::Identify the new disk:
:::code lsblk -o NAME,SIZE,FSTYPE,LABEL,UUID,MODEL,SERIAL,MOUNTPOINTS :::For a new Linux-only SATA disk using EXT4, add it to /etc/fstab:
Mount and verify it:
:::code systemctl daemon-reload mount /mnt/hdd/satadisk01 findmnt /mnt/hdd/satadisk01 :::Create the required media directory. For example:
:::code mkdir -p /mnt/hdd/satadisk01/movies :::14. Expand mergerfs to Include USB and SATA Disks
The existing mergerfs configuration only includes USB disks:
:::code /mnt/hdd/usbdisk* :::Once an internal SATA disk is added, mergerfs must include both USB and SATA branches.
Change the existing mergerfs source from:
:::code /mnt/hdd/usbdisk* :::to:
:::code /mnt/hdd/usbdisk*:/mnt/hdd/satadisk* :::The updated /etc/fstab entry becomes:
Now mergerfs will include storage such as:
:::code /mnt/hdd/usbdisk01 /mnt/hdd/usbdisk02 /mnt/hdd/usbdisk03 /mnt/hdd/satadisk01 /mnt/hdd/satadisk02 :::Remount the pool after changing the branch configuration.
:::code pct stop 101 umount /mnt/media systemctl daemon-reload mount /mnt/media pct start 101 :::Verify the pool:
:::code findmnt /mnt/media df -h /mnt/media :::Jellyfin does not require any library changes. It will continue using:
:::code /media/movies /media/music /media/series :::Final Storage Layout
:::code USB Disk 1 - NTFS /mnt/hdd/usbdisk01 ├── music └── series │ │ USB Disk 2 - exFAT /mnt/hdd/usbdisk02 ├── music └── movies │ │ Future USB Disk /mnt/hdd/usbdisk03 └── movies │ │ Internal SATA Disk - EXT4 /mnt/hdd/satadisk01 └── movies │ ▼ mergerfs │ ▼ /mnt/media ├── movies ├── music └── series │ ▼ Proxmox Bind Mount │ ▼ Jellyfin LXC /media ├── movies ├── music └── series :::NTFS, exFAT, EXT4, USB, and SATA Considerations
mergerfs does not require all storage devices to use the same filesystem or connection type.
For example, one pool can contain:
:::code USB Disk 1 = NTFS USB Disk 2 = exFAT USB Disk 3 = EXT4 SATA Disk 1 = EXT4 :::This is useful when existing USB drives already contain media and should not be reformatted.
For new disks dedicated permanently to Proxmox, a native Linux filesystem such as EXT4 is generally simpler than NTFS or exFAT.
The connection type does not affect how Jellyfin sees the library. USB and SATA disks are simply storage branches behind mergerfs.
Important Notes
- Disk 1 in this example is a USB disk using NTFS.
- Disk 2 is a USB disk using exFAT.
- USB disks use mount points such as
/mnt/hdd/usbdisk01. - Future internal SATA disks can use mount points such as
/mnt/hdd/satadisk01. - mergerfs can combine USB and SATA disks in the same pool.
- mergerfs can combine different disk capacities and filesystems.
- The minimum free-space threshold in this setup is 500 MB.
- Existing media disks do not need to be reformatted.
- Keep media folder names consistent across all disks.
- mergerfs is not RAID and does not provide redundancy by itself.
- If one disk fails, files stored on that disk may be lost while files on other disks remain independent.
- SnapRAID can be added later if parity protection is required.
Conclusion
mergerfs provides a flexible way to expand Jellyfin storage on Proxmox without creating a traditional RAID array or managing separate libraries for every physical disk.
In this example, the storage pool starts with an NTFS USB disk mounted at /mnt/hdd/usbdisk01 and an exFAT USB disk mounted at /mnt/hdd/usbdisk02.
Additional USB disks can continue using the usbdisk naming convention, while future internal SATA disks can use mount points such as /mnt/hdd/satadisk01.
When SATA disks are introduced, the mergerfs branch configuration can be expanded from:
:::code /mnt/hdd/usbdisk* :::to:
:::code /mnt/hdd/usbdisk*:/mnt/hdd/satadisk* :::All disks are then presented through the same /mnt/media pool, while Jellyfin continues accessing only /media/movies, /media/music, and /media/series.
This allows the Jellyfin storage pool to grow over time without changing the existing Jellyfin library configuration.
:::toc enable
Post a Comment for "How to Expand Jellyfin Storage with mergerfs on Proxmox LXC"
Post a Comment