storage_manager [Batocera.linux

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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.

<WRAP tip>
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.
</WRAP>

{{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:

<code>
/userdata/roms
</code>

Batocera handles the storage pool in the background.

{{wiki:use_external_storage_storage_overview_diagram.png?nolink&576|Storage Manager overview}}

A simplified overview:

<code>
Internal ROMs
     │
Drive 1 /roms
     │
Drive 2 /roms
     │
  MergerFS
     │
/userdata/roms
</code>

===== Requirements =====

A drive must contain a root-level folder named:

<code>
roms
</code>

Supported:

<code>
Drive
└── roms
    ├── nes
    ├── snes
    └── psx
</code>

Not supported:

<code>
Drive
└── Batocera
    └── roms
</code>

Not supported:

<code>
Drive
├── nes
├── snes
└── psx
</code>

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}}

<WRAP important>
Formatting a drive will permanently erase all existing data stored on that drive. Make sure any important files have been backed up before proceeding.
</WRAP>

																				

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:

<code>
/media/roms1/roms
/media/roms2/roms
</code>

Batocera combines them into a single virtual library:

<code>
/userdata/roms
</code>

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:

<code>
/media/roms1/roms
/media/roms2/roms
</code>

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

<WRAP info>
The drive name does not matter. What matters is that the mounted drive contains a root-level ''roms'' folder.
</WRAP>

===== 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:

<code>
/userdata/roms
</code>

Folders such as:

<code>
/userdata/bios
/userdata/saves
/userdata/screenshots
/userdata/themes
/userdata/music
</code>

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:

<code>
/userdata/roms
</code>

are moved into:

<code>
/userdata/.roms_base
</code>

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:

<code>
<drive>/roms
</code>

Nested ROM folders are not detected automatically.

Example:

<code>
<drive>/Batocera/roms
</code>

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:

<code>
/userdata/roms
</code>

Internally, Batocera maintains a storage pool containing:

<code>
/userdata/.roms_base
</code>

plus any merged ROM folders.

Example:

<code>
/userdata/.roms_base
/media/roms1/roms
/media/roms2/roms
</code>

These locations are combined into:

<code>
/userdata/roms
</code>

==== MergerFS File Placement Policy ====

Batocera currently uses the following MergerFS create policy:

<code>
category.create=eplfs
moveonenospc=true
minfreespace=4G
</code>

**eplfs** means:

<code>
Existing Path, Least Free Space
</code>

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:

<code>
/media/roms1/roms/nes   900 GB free
/media/roms2/roms/nes   200 GB free
</code>

A new ROM copied into:

<code>
/userdata/roms/nes
</code>

would be stored on:

<code>
/media/roms2/roms/nes
</code>

because it has the least free space while still meeting the minimum free space requirement.

<WRAP important>
The MergerFS implementation and file placement policy may change between Batocera releases. This section reflects the behavior introduced with Batocera v43.
</WRAP>

===== 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:

<code>
/media/roms1/roms
/media/roms2/roms
</code>

==== 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:

<code>
/userdata/roms
</code>

is merged.

BIOS files remain stored in:

<code>
/userdata/bios
</code>

==== Are saves merged? ====

No.

Save files remain stored in the normal userdata location, for example:

<code>
/userdata/saves
</code>

==== Can I store ROMs in a different folder? ====

No.

The Storage Manager currently expects a root-level folder named:

<code>
roms
</code>

==== Does the drive name matter? ====

No.

For example, both of these are valid if they contain a root-level ''roms'' folder:

<code>
/media/roms1/roms
/media/MyGamesDrive/roms
</code>

===== 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