ROM Librarian

A cross-platform desktop application for managing, organizing, and maintaining retro gaming ROM collections.

Features

Rename Tab

Regex-based batch renaming with live preview
Preset patterns for common cleanup tasks:
- Remove region tags (USA, Europe, Japan)
- Clean translation tags
- Remove GoodTools dump tags
- Convert underscores to spaces
Collision detection with multiple handling strategies
Select All/Deselect All buttons for batch operations
Auto-update gamelist.xml - Automatically updates EmulationStation/RetroPie metadata when renaming files
CUE file awareness - Automatically updates CUE file contents when renaming BIN files (keeps disc images intact)
Undo support for the last rename operation (includes gamelist.xml restoration)

DAT Rename Tab

No-Intro DAT file support for accurate ROM naming
Multi-hash matching - Uses CRC32, MD5, and SHA1 for precise identification
ZIP file support - Hashes ROM files inside zip archives for matching
Live preview - See matched files before renaming
Smart filtering - Skip files already correctly named
Sortable columns - Click column headers to sort results
Selection tools - Select All/Deselect All with click-and-drag support
Unmatched file tracking - Shows files that couldn't be matched (for manual review)
Export functionality - Export list of unmatched files
Auto-update gamelist.xml - Maintains EmulationStation/RetroPie metadata
CUE file awareness - Automatically updates CUE file contents when renaming BIN files
Refresh button - Rescan after operations in other tabs
Full undo support with tree updates and gamelist.xml restoration

Compression Tab

Dual-pane interface showing uncompressed ROMs and compressed archives
ZIP and 7z compression - choose your archive format via radio buttons
Batch compress ROMs to ZIP or 7z format (no external tools required)
Batch extract ZIP and 7z archives
Auto-detection of ROM file types in folder
Status tracking - archives marked "Extracted" when their ROM counterpart exists
Safe cleanup - "Delete Archived Only" and "Delete Extracted Only" buttons for safe one-click cleanup after operations

Conversion Tab

CHD format conversion for disc images used with MAME/RetroArch
CUE/BIN → CHD - Convert PlayStation and other disc images to compressed CHD format
ISO → CHD - Convert ISO disc images to CHD format
Smart validation - Automatically validates BIN file references in CUE files
Bulk conversion - Convert selected files or all files at once
Source cleanup - Optional deletion of source files after successful conversion
Progress tracking - Real-time progress with detailed error reporting
Bundled chdman - No separate installation required (Windows; Linux users need chdman in PATH)

M3U Creation Tab

Multi-disc game detection (Disc 1, Disc 2, CD1, etc.)
Automatic M3U playlist generation for emulators
Organized storage - Moves disc files to .hidden folder
Keeps your game list clean with one entry per multi-disc game

Duplicates Tab

Content-based duplicate detection using SHA1/MD5 hashing
Persistent hash caching - Re-scans are lightning fast when files haven't changed
Multiple scan modes: single folder, with subfolders, or entire ROM library
Smart auto-selection strategies:
- Keep by region preference (USA > Europe > Japan)
- Keep largest/smallest file
- Keep oldest/newest file
Export duplicate reports to text file
Archive awareness - Note: Archives are compared as files, not by ROM content inside (extract first for accurate detection)

Compare Collections Tab

Compare two ROM collections to find differences
Quick compare (by filename) or Deep compare (by content hash)
Integrity verification for matching files
Copy missing files between collections
Export missing file lists

Updates Menu

Auto-updater - Automatically check for new releases from GitHub
Check on Startup toggle (enabled by default)
Manual update check - "Check for Updates" option
Release notes preview - See what's new before updating

CLI Mode (Linux / Headless)

No display required - runs on NAS devices, servers, and systems without a desktop environment
rename - regex-based batch renaming with collision handling
compress - ZIP or 7z compression by file extension
extract - extract ZIP/7z archives
dat-rename - hash-match and rename using No-Intro/MAME DAT files
Scriptable - --yes flag skips all confirmation prompts for use in scripts

Installation

Windows

For End Users (Recommended)

Download the latest ROM-Librarian-vX.X.X-Windows.zip from the Releases page
Extract the ZIP file to any location on your computer
Run ROM Librarian.exe from the extracted folder

No Python installation required! The application is fully portable.

Linux

For End Users (Recommended)

Download the latest ROM-Librarian-vX.X.X-Linux.tar.gz from the Releases page

Extract the archive:

tar -xzf ROM-Librarian-vX.X.X-Linux.tar.gz

Make executable (if needed):
```
chmod +x ROM-Librarian
```
Run the application:
```
./ROM-Librarian
```

Note: The Linux version runs without themes for maximum compatibility across distributions.

Headless / NAS Usage (No Desktop Environment)

If your system has no display (NAS, server, headless Linux), use CLI mode:

./ROM-Librarian --cli --help

See the CLI Mode section below for full documentation.

For Developers

Prerequisites

Python 3.8 or higher
tkinter (usually included with Python)

Install Dependencies

Windows:

pip install -r requirements.txt

Linux:

pip install py7zr
pip install ttkbootstrap  # Optional - not recommended on Linux

Note: On Linux, the app works best without ttkbootstrap due to compatibility issues with some distributions.

Run from Source

python rom_manager.py

Building Releases

Windows:

build_release.bat

Linux:

pyinstaller rom_manager.py --onefile --noconsole --name "ROM-Librarian" \
  --hidden-import=PIL --hidden-import=PIL._tkinter_finder \
  --hidden-import=PIL.Image --hidden-import=PIL.ImageTk \
  --clean --noconfirm

Usage

Select a ROM folder using the Browse button at the top
Navigate between tabs to access different features
Preview changes before applying (rename operations show previews)
Use tooltips - Hover over buttons for 1-2 seconds to see descriptions

CLI Mode

ROM Librarian includes a headless CLI for systems without a desktop environment — NAS devices, servers, or any Linux box without a display.

Invoking CLI mode

Using the compiled binary:

./ROM-Librarian --cli <command> [options]

Running from source:

python cli.py <command> [options]
# or
python rom_manager.py --cli <command> [options]

Commands

`rename` — Regex-based batch rename

./ROM-Librarian --cli rename <folder> --pattern <regex> --replace <str> [options]

Option	Description
`--pattern`, `-p`	Regex pattern to match (required)
`--replace`, `-r`	Replacement string, use `""` to delete matches (required)
`--collision`	How to handle name collisions: `skip` (default), `suffix`, `keep_first`
`--yes`, `-y`	Skip confirmation prompt (for scripts)

Examples:

# Remove region tags like (USA), (Europe), (Japan)
./ROM-Librarian --cli rename /mnt/roms/gba --pattern " \((?!Disc [0-9])[^)]*\)" --replace ""

# Remove all parentheses content
./ROM-Librarian --cli rename /mnt/roms/nes --pattern " \([^)]*\)" --replace ""

# Replace underscores with spaces
./ROM-Librarian --cli rename /mnt/roms/snes --pattern "_" --replace " "

# Non-interactive (for use in scripts)
./ROM-Librarian --cli rename /mnt/roms/gba --pattern " \(USA\)" --replace "" --yes

`compress` — Compress ROMs to ZIP or 7z

./ROM-Librarian --cli compress <folder> --ext <ext> [options]

Option	Description
`--ext`	File extension to compress, e.g. `.gba` or `*.smc` (required)
`--format`	Archive format: `zip` (default) or `7z`
`--delete-originals`	Delete original files after successful compression
`--yes`, `-y`	Skip confirmation prompt

Examples:

# Compress all GBA ROMs to ZIP
./ROM-Librarian --cli compress /mnt/roms/gba --ext .gba

# Compress to 7z and delete originals
./ROM-Librarian --cli compress /mnt/roms/snes --ext .smc --format 7z --delete-originals --yes

`extract` — Extract ZIP/7z archives

./ROM-Librarian --cli extract <folder> [options]

Option	Description
`--delete-archives`	Delete archives after successful extraction
`--yes`, `-y`	Skip confirmation prompt

Examples:

# Extract all archives in folder
./ROM-Librarian --cli extract /mnt/roms/gba

# Extract and remove archives
./ROM-Librarian --cli extract /mnt/roms/gba --delete-archives --yes

`dat-rename` — Rename using a No-Intro/MAME DAT file

Hashes each ROM (CRC32/MD5/SHA1) and renames it to the canonical name from the DAT.

./ROM-Librarian --cli dat-rename <folder> --dat <dat_file> [options]

Option	Description
`--dat`	Path to the DAT file (required)
`--yes`, `-y`	Skip confirmation prompt

Examples:

# Match and rename GBA ROMs using a No-Intro DAT
./ROM-Librarian --cli dat-rename /mnt/roms/gba --dat "No-Intro - GBA.dat"

# Non-interactive
./ROM-Librarian --cli dat-rename /mnt/roms/gba --dat /dats/gba.dat --yes

Common options

All commands support --yes / -y to skip confirmation prompts, which is useful when calling from shell scripts or cron jobs.

# Example: nightly script to compress new ROMs
#!/bin/bash
/opt/rom-librarian/ROM-Librarian --cli compress /mnt/roms/gba --ext .gba --delete-originals --yes

Supported ROM Formats

Cartridge-based Systems

.nds, .gba, .gbc, .gb, .sfc, .smc, .nes, .n64, .z64, .v64, .md, .smd, .gen, .gg, .sms, .pce, .ngp, .ngc, .ws, .wsc

Disc-based Systems

.bin, .iso, .cue, .chd, .cso, .gcm, .rvz, .wbfs, .wad

Modern Systems

.dol, .elf, .nsp, .xci, .nca

Platform Notes

Windows

Full theme support (light/dark modes)
All features fully functional
Sleep prevention during long operations

Linux

Runs on most distributions including Steam Deck
No theme support (plain Tk interface)
Some features may have limited functionality on certain distributions
Tested on Ubuntu, Arch Linux, and SteamOS
Headless / NAS support via CLI mode — no display or desktop environment required (see CLI Mode)

Credits

Developed by: RobotWizard
Built with: Claude Code by Anthropic
App Icon: Game cartridge icons by Creatype - Flaticon

License

MIT License - See LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
.github/workflows		.github/workflows
core		core
docs		docs
operations		operations
parsers		parsers
tests		tests
ui		ui
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
RELEASE_GUIDE.md		RELEASE_GUIDE.md
build_release.bat		build_release.bat
cartridge.ico		cartridge.ico
chdman.exe		chdman.exe
cli.py		cli.py
requirements.txt		requirements.txt
rom_librarian.spec		rom_librarian.spec
rom_manager.py		rom_manager.py

Folders and files

Latest commit

History

Repository files navigation

ROM Librarian

Features

Rename Tab

DAT Rename Tab

Compression Tab

Conversion Tab

M3U Creation Tab

Duplicates Tab

Compare Collections Tab

Updates Menu

CLI Mode (Linux / Headless)

Installation

Windows

For End Users (Recommended)

Linux

For End Users (Recommended)

Headless / NAS Usage (No Desktop Environment)

For Developers

Prerequisites

Install Dependencies

Run from Source

Building Releases

Usage

CLI Mode

Invoking CLI mode

Commands

rename — Regex-based batch rename

compress — Compress ROMs to ZIP or 7z

extract — Extract ZIP/7z archives

dat-rename — Rename using a No-Intro/MAME DAT file

Common options

Supported ROM Formats

Cartridge-based Systems

Disc-based Systems

Modern Systems

Archives

Platform Notes

Windows

Linux

Credits

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors 2

Languages

`rename` — Regex-based batch rename

`compress` — Compress ROMs to ZIP or 7z

`extract` — Extract ZIP/7z archives

`dat-rename` — Rename using a No-Intro/MAME DAT file

Packages