====== Storage Manager ======
{{toc>}}
> Introduced in **Batocera v43**.
Batocera's **Storage Manager** allows you to expand your ROM storage across multiple drives while keeping a single unified game library.
USB drives, external hard drives, SSDs, SD cards, and additional internal drives can all be used.
The Storage Manager introduced in Batocera v43 allows multiple drives to be combined into a single ROM library without requiring symbolic links, manual mounts, or custom scripts.
{{wiki:use_external_storage_system_settings.png?nolink&576|Storage Manager location in System Settings}}
===== Overview =====
The Storage Manager can:
* Detect compatible storage devices automatically
* Merge existing ROM drives
* Format and prepare new drives
* Use multiple drives simultaneously
* Present all ROMs as a single library under ''/userdata/roms''
* Safely eject drives
* Automatically refresh game lists
From the user's point of view, there is still only one ROM folder:
/userdata/roms
Batocera handles the storage pool in the background.
{{wiki:use_external_storage_storage_overview_diagram.png?nolink&576|Storage Manager overview}}
A simplified overview:
Internal ROMs
│
Drive 1 /roms
│
Drive 2 /roms
│
MergerFS
│
/userdata/roms
===== Requirements =====
A drive must contain a root-level folder named:
roms
Supported:
Drive
└── roms
├── nes
├── snes
└── psx
Not supported:
Drive
└── Batocera
└── roms
Not supported:
Drive
├── nes
├── snes
└── psx
The Storage Manager currently expects the ''roms'' folder to exist directly in the root of the mounted drive.
===== Using Existing Drives =====
When Batocera detects a mounted drive containing a compatible root-level ''roms'' folder, it offers to merge the drive into the Storage Manager.
{{wiki:use_external_storage_merge_existing_drive_prompt.png?nolink&576|Merge existing drive prompt}}
After accepting the prompt, Batocera adds the drive to the storage pool.
{{wiki:use_external_storage_merge_existing_drive_complete.png?nolink&576|Merge complete}}
After the merge completes, the ROMs stored on the drive become available alongside your existing collection.
===== Formatting a New Drive =====
If a blank drive is detected, Batocera can automatically prepare it for game storage.
{{wiki:use_external_storage_format_new_drive_prompt.png?nolink&576|Format and merge prompt}}
Formatting a drive will permanently erase all existing data stored on that drive. Make sure any important files have been backed up before proceeding.
Selecting **Format & Merge** will format the drive and add it to the Storage Manager.
{{wiki:use_external_storage_format_confirmation.png?nolink&576|Format confirmation}}
Batocera will:
* Format the drive
* Create a root-level ''roms'' folder
* Generate the standard ROM directory structure
* Merge the drive into the Storage Manager
* Refresh the game lists
{{wiki:use_external_storage_formatting_drive.png?nolink&576|Formatting drive}}
===== Using Multiple Drives =====
Multiple drives can be used simultaneously.
Example:
/media/roms1/roms
/media/roms2/roms
Batocera combines them into a single virtual library:
/userdata/roms
Games can be distributed across multiple drives while still appearing as one collection inside EmulationStation.
===== Internal Drives =====
The Storage Manager is not limited to removable USB devices.
Additional internal drives can also be used.
For example:
/media/roms1/roms
/media/roms2/roms
As long as the drive is mounted by Batocera and contains a root-level ''roms'' folder, it can be merged into the Storage Manager.
This includes:
* SATA hard drives
* SATA SSDs
* NVMe SSDs
* USB storage devices
* SD cards
The drive name does not matter. What matters is that the mounted drive contains a root-level ''roms'' folder.
===== Safe Drive Removal =====
Drives can be safely removed from:
* **Main Menu**
* **System Settings**
* **Eject an Extra Disk**
{{wiki:use_external_storage_safe_eject_menu.png?nolink&576|Safe eject menu}}
After selecting the drive, Batocera asks for confirmation before removing it from the storage pool.
{{wiki:use_external_storage_safe_eject_confirmation.png?nolink&576|Eject confirmation}}
Batocera automatically updates the storage pool and refreshes the game lists.
{{wiki:use_external_storage_drive_ejected.png?nolink&576|Drive ejected}}
Games stored only on the removed drive will disappear from the library until that drive is connected and merged again.
===== What Gets Merged? =====
Only the ROM library is merged:
/userdata/roms
Folders such as:
/userdata/bios
/userdata/saves
/userdata/screenshots
/userdata/themes
/userdata/music
remain on internal storage.
The Storage Manager does not merge BIOS files, save files, screenshots, themes, or music.
===== Internal ROM Preservation =====
When the first additional ROM drive is merged, Batocera preserves the existing internal ROM collection.
Internally, existing ROMs stored in:
/userdata/roms
are moved into:
/userdata/.roms_base
This allows internal ROMs to remain visible alongside ROMs stored on merged drives.
If all merged drives are later removed, Batocera restores the internal ROM library back to the normal ''/userdata/roms'' location.
===== Limitations =====
The Storage Manager currently requires this layout:
/roms
Nested ROM folders are not detected automatically.
Example:
/Batocera/roms
is not automatically merged.
Only the ROM library is merged. Other userdata folders remain independent.
===== Advanced Technical Details =====
Batocera uses **MergerFS** to combine ROM folders from multiple drives into a single virtual directory.
The merged library is presented at:
/userdata/roms
Internally, Batocera maintains a storage pool containing:
/userdata/.roms_base
plus any merged ROM folders.
Example:
/userdata/.roms_base
/media/roms1/roms
/media/roms2/roms
These locations are combined into:
/userdata/roms
==== MergerFS File Placement Policy ====
Batocera currently uses the following MergerFS create policy:
category.create=eplfs
moveonenospc=true
minfreespace=4G
**eplfs** means:
Existing Path, Least Free Space
When writing a new file:
* MergerFS looks for branches where the target folder already exists
* Among those branches, the branch with the least free space is preferred
* Branches with less than 4 GB free are ignored
* If a drive becomes full during a write operation, the file can automatically move to another branch
Example:
/media/roms1/roms/nes 900 GB free
/media/roms2/roms/nes 200 GB free
A new ROM copied into:
/userdata/roms/nes
would be stored on:
/media/roms2/roms/nes
because it has the least free space while still meeting the minimum free space requirement.
The MergerFS implementation and file placement policy may change between Batocera releases. This section reflects the behavior introduced with Batocera v43.
===== Frequently Asked Questions =====
==== Can I use internal drives? ====
Yes. Any drive mounted by Batocera containing a root-level ''roms'' folder can be merged into the Storage Manager.
Example:
/media/roms1/roms
/media/roms2/roms
==== What happens if I unplug a merged drive? ====
Batocera updates the storage pool and refreshes the game lists.
Games stored only on the disconnected drive will temporarily disappear until the drive is connected again.
==== Are BIOS files merged? ====
No.
Only:
/userdata/roms
is merged.
BIOS files remain stored in:
/userdata/bios
==== Are saves merged? ====
No.
Save files remain stored in the normal userdata location, for example:
/userdata/saves
==== Can I store ROMs in a different folder? ====
No.
The Storage Manager currently expects a root-level folder named:
roms
==== Does the drive name matter? ====
No.
For example, both of these are valid if they contain a root-level ''roms'' folder:
/media/roms1/roms
/media/MyGamesDrive/roms
===== References =====
* Batocera TV — ''Batocera 43 - Episode II''
* Storage Manager demonstration:
* https://youtu.be/XpH27Yswe38?t=143
* Batocera Storage Manager source code:
* https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-scripts/scripts/batocera-storage-manager