Skip to content

RomM File Structure & Scanning

How to organize ROM files so RomM correctly identifies platforms, matches metadata, and handles multi-disc games.

Overview

RomM does not have a drop folder or auto-watch feature. You place files in the library directory and trigger a scan manually (via the web UI or API). Scans can also be scheduled via cron or automation.

Library Structure

RomM expects this exact hierarchy:

library/
  roms/
    <platform_slug>/
      SingleFileGame.zip
      MultiDiscGame/
        disc1.bin
        disc1.cue
        disc2.bin
        disc2.cue
  bios/
    <platform_slug>/
      bios_file.bin

Rules

  • The top-level directory must be roms/ (and optionally bios/) inside the library root
  • Each platform gets its own subdirectory using the IGDB platform slug
  • Single-file ROMs go directly in the platform folder (any format: .zip, .7z, .iso, .bin, .nes, etc.)
  • Multi-file ROMs (e.g., multi-disc PSX games) go in a subfolder named after the game
  • BIOS files follow the same platform slug convention under bios/

Common Platform Slugs

Folder name Platform
gb Game Boy
gbc Game Boy Color
gba Game Boy Advance
nes NES / Famicom
snes SNES / Super Famicom
n64 Nintendo 64
nds Nintendo DS
3ds Nintendo 3DS
ngc GameCube
wii Wii
nswitch Nintendo Switch
psx PlayStation
ps2 PlayStation 2
psp PSP
smd Sega Genesis / Mega Drive
dreamcast Dreamcast
saturn Sega Saturn

The full list of 400+ supported platforms is in the RomM docs.

Multi-Disc Games (PSX, PS2, etc.)

For games that span multiple discs, create a subfolder named after the game:

roms/
  psx/
    Crash Bandicoot (USA).bin
    Crash Bandicoot (USA).cue
    Final Fantasy VII (USA)/
      Final Fantasy VII (USA) (Disc 1).bin
      Final Fantasy VII (USA) (Disc 1).cue
      Final Fantasy VII (USA) (Disc 2).bin
      Final Fantasy VII (USA) (Disc 2).cue
      Final Fantasy VII (USA) (Disc 3).bin
      Final Fantasy VII (USA) (Disc 3).cue

RomM treats the subfolder as a single game entry with multiple files.

Triggering Scans

Since there's no auto-watch, scans must be triggered:

  • Web UI: Click the scan button in the RomM dashboard
  • API: POST /api/raw/platforms or use the scan endpoints
  • Automation: Schedule via cron, n8n, or a Forgejo Actions workflow

Docker Volume Mapping

volumes:
  - /path/to/roms:/romm/library/roms
  - /path/to/bios:/romm/library/bios
  - /path/to/assets:/romm/assets
  - /path/to/config:/romm/config

References