Storage Manager

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

A simplified overview:

Internal ROMs
     │
Drive 1 /roms
     │
Drive 2 /roms
     │
  MergerFS
     │
/userdata/roms

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.

When Batocera detects a mounted drive containing a compatible root-level roms folder, it offers to merge the drive into the Storage Manager.

After accepting the prompt, Batocera adds the drive to the storage pool.

After the merge completes, the ROMs stored on the drive become available alongside your existing collection.

If a blank drive is detected, Batocera can automatically prepare it for game storage.

Selecting Format & Merge will format the drive and add it to the Storage Manager.

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

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.

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

Drives can be safely removed from:

• Main Menu
• System Settings
• Eject an Extra Disk

After selecting the drive, Batocera asks for confirmation before removing it from the storage pool.

Batocera automatically updates the storage pool and refreshes the game lists.

Games stored only on the removed drive will disappear from the library until that drive is connected and merged again.

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.

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.

The Storage Manager currently requires this layout:

<drive>/roms

Nested ROM folders are not detected automatically.

Example:

<drive>/Batocera/roms

is not automatically merged.

Only the ROM library is merged. Other userdata folders remain independent.

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

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.

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

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.

No.

Only:

/userdata/roms

is merged.

BIOS files remain stored in:

/userdata/bios

No.

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

/userdata/saves

No.

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

roms

No.

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

/media/roms1/roms
/media/MyGamesDrive/roms

• 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