Skip to content
BlizzHackerPublic

About

Find, verify and organize your game library. Native Windows and Docker, DAT checks, ROM Hub plugins, and optional RomM/Cartridge integration.

Topics

Resources

Security policy

Stars

382 stars

Watchers

5 watching

Forks

Latest commit

 

History

598 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ROMarr

ROMarr — Find, verify and organize your game library

The *arr for games.

Find games, verify ROMs, and import them into your library.

New here? Start with one system and one game. ROMarr finds and organizes; an emulator plays. RomM is an optional library frontend. You can bring files you already own or connect search sources when you are ready.

Tests and images License: MIT Discord Open Collective GG Requestz RomM Ecosystem r/romm r/arr Android Beta Android APK Argosy Compatible Unraid Community Apps Microsoft Store Submit Package

Install · First setup · Discord · Open Collective · GG Requestz · RomM · r/romm · r/arr · Android App & APK · Unraid App · Plugins · Roadmap · Releases · Submit Package · Privacy

Note

Community & Support:
Join the official ROMarr Discord, follow or sponsor the project on Open Collective, or hang out on Reddit in r/romm and r/arr. Connect companion game request workflows via GG Requestz and frontend setups via RomM.

Tip

Android Beta, Handhelds & Argosy Launcher Integration!
Run ROMarr natively on your phone, tablet, or gaming handheld (Ayn Odin, Retroid Pocket, Anbernic, Logitech G Cloud):

  • Google Play Test Track: Join the Android Beta on Google Play (12 testers needed)
  • Direct APK Sideload: Download the Standalone APK with bundled Chaquopy Python runtime — no Termux or Docker required.
  • Argosy Launcher & Emulator Pairing: Connect Argosy Launcher directly to ROMarr via native RomM API support, and launch games into RetroArch, Dolphin, PPSSPP, NetherSX2, DuckStation, and Citra with one tap!

ROMarr interactive search, with scores and reasons beside each result

Forks and code reuse are welcome; independent projects should use their own branding. Attribution and branding policy.

Unraid: install the official ROMarr listing, using ghcr.io/blizzhacker/romarr. ROMarrNG is a separate fork and is not supported by this project. Official builds and support policy.

What can I use it for?

I want to… Start here What you need
Import ROMs I already have Manual Import A destination folder and access to the source files. No indexer or download client needed.
Find and download a particular game Add New or Interactive Search A search source, a matching download client, and a destination folder.
Check what a collection is missing Collections A No-Intro or Redump DAT and your local library.
Report a suspicious or unwanted file Activity → Reports & Help A relative library path; available scanners record evidence, quarantine is your choice. How reporting works.
Connect an AI assistant Hub → Library Shell → AI agents (MCP) Your server URL and API key. Claude, Codex, Hermes and Antigravity setup.
Reclaim space taken by exact duplicates Stats → Audit A local library; review the preview before moving duplicates to quarantine. Restore is available.
Add another game source Hub → Plugins ROM Hub, included in the Windows app and amd64/arm64 Docker images. Details.
Adopt an existing RomM collection Settings → Library & Hub Point ROMarr at RomM's roms directory, keep DAT verification automatic, and pair with Argosy Launcher.
Sync with Handhelds & Emulators Hub → Handheld Fleet Sync verified libraries to Android handhelds, Steam Deck, Batocera, RetroPie, and muOS with 1,200+ emulator presets.

You can use a plain folder as your library. RomM, Gaseous, Retrom and other library integrations are optional. Your emulator or frontend plays the games; ROMarr handles finding, checking and importing files.

Imports can be checked against DAT checksums. The result is verified, bad dump, or unknown. Without a matching DAT, a file is unknown; that does not mean it is damaged. Rename on import can use a verified single-file ROM's DAT name while keeping its source extension; unknown filenames are retained and existing files are not overwritten. For files already in your library, use the rename preview and rollback guide. Review each proposed change; multi-file disc sets and ambiguous matches are skipped.

Editions & Screenshots

ROMarr shares one unified interface across browser deployments, Windows standalone, Android phones/handhelds, and ROMarr.app. All captures below are taken from a live 76,064-game library running ROMarr v1.10.0.

Platform Editions & Authentication

Edition Highlights Preview
Browser Web UI 76,064 games cached across 73 platforms with cover art, fast filters, and status badges ROMarr Browser Edition — 76,064 games across 73 platforms
Windows Desktop App Portable x64 WebView2 window, tray host, Cartridge player menu, and 1,220-entry Emulator Hub ROMarr Windows Desktop Edition with Cartridge menu and Emulator Hub
Android App (Mobile & Handhelds) Bundled Chaquopy server plus HTTPS remote profile switching over mobile touch UI ROMarr Android App connected to a remote server
Android Slide-Out Drawer Touch navigation drawer with expandable hub sections and integrated Color Changer ROMarr Android navigation drawer and theme controls
ROMarr.app Website Project landing page synced with real scored search results and live accent swatches ROMarr.app landing page showcase
Sign-In & OIDC SSO Built-in password/API-key authentication alongside external SSO providers such as Authentik ROMarr sign-in and OIDC SSO screen

Vector SVG Branding & Live Color Changer

The separated vector icon (romarr-icon.svg) and stacked lockup dynamically bind to var(--accent) so the logo, wordmark, active navigation, and charts shift cleanly together in real time:

Steel Blue (#75adff) Warm Amber (#f2a33c) Emerald Green (#3ecf6d) Royal Violet (#c084fc)
Steel Blue accent theme Warm Amber accent theme Emerald Green accent theme Royal Violet accent theme

Library Discovery, Confined Plugins & Device Sync

Feature Preview
Library Overview — 76,056 files on disk, platform pills, genre/region/decade filters, and cover grid ROMarr library view across 73 platforms
Discover Shelf — 42,210 metadata-matched games from your library with top-rated, hidden-gem, and franchise filters ROMarr Discover shelf with 42,210 games
ROM Hub Plugins — 40+ confined subprocess sources across ROMs (archive-org, vimm-net, minerva-archive, theromdepot), mods (curseforge, moddb, nexusmods, modrinth, thunderstore, gamebanana), guides/tutorials (gamefaqs, strategywiki, game-manuals, youtube-tutorials), and open-source games & bots (github-games) ROM Hub showing enabled plugins
Device Fleet & 1G1R Planner — Non-destructive Igir sync plans and frontend exports for ES-DE, RetroPie, Batocera, Steam Deck, and Argosy Device Fleet non-destructive 1G1R sync planner
Tour more views: MCP AI Connector, Device Cards, Emulator Hub, Collections, Friends & System Telemetry
View Preview
Device Profiles & Handheld Cards Device Fleet cards for ES-DE, RetroPie, Batocera, Steam Deck, and Android handhelds
AI Agents (MCP) Connector Authenticated MCP endpoint config for Claude Code, Codex, Hermes, and Antigravity
Emulator Hub & Cartridge Setup Cartridge plug-and-play toolbar and 1,220-entry Emulator Hub
Ecosystem (Igir v5.8.0 & Backends) Igir v5.8.0 runner and RomM/Gaseous/Retrom/Gameyfin integrations
Collections & Set Torrents 1G1R DAT comparison and budgeted qBittorrent set acquisition
Statistics & Indexer Telemetry Library totals, platform imports, and grabs by indexer
Friends & Federation Confirmed peer invitations and 198,106-hash netplay verification
Browse Shared Friend Shelf Browsing a peer server library and adding titles to Wanted
Import Lists & Storefront Connectors One-click Steam, GOG, Epic, Battle.net, PlayStation, Xbox, and itch.io lists
Storefront Session Token Modal PlayStation session paste modal in dark Steel Blue UI
Activity History Grabbed, ignored, and failed event trail with indexer sources
Notification Providers Discord, Slack, Webhook, ntfy.sh, Gotify, Telegram, Pushover, and Apprise
Library Backends Configured library destinations and status checks
System Health & GG Requestz Service health checks and GG Requestz webhook configuration
Scheduled Tasks Automated import, missing search, RSS, list sync, and hash indexing tasks
Live Process Logs Streaming service logs inside the web interface

Install

Choose a method

Method Best fit Guide
Unraid Unraid NAS & server arrays Install from Unraid Community Applications
Docker Compose Most servers, NAS hosts, or Docker Desktop Quick start below
Windows app Windows 10/11 on x64 Download the Windows ZIP, extract it and double-click ROMarr.exe. No Python, PowerShell or .NET installation required.
macOS, Linux & SteamOS Desktop PCs, MacBooks, Steam Deck & Handhelds (Non-Server) Standalone Desktop Launcher: run ./scripts/start-desktop.sh
Android & Handhelds Android 7+ on ARM64/x86_64 (Odin, Retroid, phones, tablets) Join Google Play Beta or download APK from Releases. Embedded Chaquopy core, emulator handoff, and Argosy Launcher compatibility. Read Android setup.
Proxmox LXC A Proxmox host LXC installer
Chrome / ChromeOS A running ROMarr server Install the web app or server-launcher extension. Online connection required.
Linux/macOS source checkout Development or an existing Python host Source instructions
Home Assistant add-on A Home Assistant installation Add-on instructions; this packaging needs more field testing.
Package Submissions Community Catalogs (TrueNAS, CasaOS, Flathub) Submission Directory & Registry Guides

For Docker, have Docker Engine or Docker Desktop with Compose installed. Reserve port 6868 and choose where settings, downloads, and ROMs will live. ROMs and download space are usually much larger than the app itself.

Docker Compose quick start

These commands are for a Linux or macOS shell, or an SSH terminal on your Docker host. They create a new folder library. If you already use RomM or another library, mount its real ROM directory instead of ./roms.

mkdir -p romarr/config romarr/roms romarr/downloads
cd romarr

Save this as compose.yaml in that directory:

services:
  romarr:
    image: ghcr.io/blizzhacker/romarr:latest
    container_name: romarr
    restart: unless-stopped
    ports:
      - "6868:6868"
    environment:
      PUID: 1000
      PGID: 1000
      UMASK: "002"
      TZ: Etc/UTC
      LIBRARY_KIND: folder
      LIBRARY_PATH: /roms
    volumes:
      - ./config:/config
      - ./roms:/roms
      - ./downloads:/downloads

Set PUID and PGID to the numeric owner/group of your ROM and download folders (id -u and id -g on Linux), then start:

docker compose up -d

Open http://localhost:6868 on that computer, or http://YOUR-SERVER-IP:6868 from another device. Set a password, then follow Settings → Setup Guide (/#setup). You can skip steps you do not need and reopen the guide later.

Already have a download client? Its completed files must be visible to ROMarr. If the client reports /downloads, both containers should use that path for the same files. A client in a different container is reached by its Docker service name on a shared network, or by its host's address; localhost inside ROMarr means ROMarr itself. Path examples and troubleshooting.

The image includes archive tools. ROM Hub is included on amd64/arm64; it is unavailable in the armv7 image. Image tags, permissions, backup and updates.

Get your first result

Already have ROMs? Put one file in the mounted downloads folder, open Manual Import, and scan /downloads. Check the platform and verification result before pressing Import. Walkthrough.

Want automatic downloads? Add a library, a download client and a search source in Setup Guide. Use Interactive Search for your first game so you can inspect the results before grabbing one. Follow it through Queue and History. Walkthrough.

Want plugins? Open Hub → Plugins, choose a plugin, click Install, and add a ROM Hub download client for searchable plugins. ROM Hub is the plugin host; each plugin adds a particular source or capability. Available examples and exact steps.

What else is included?

  • Wanted lists and scheduled searches, with the reason shown when a release is rejected.
  • Prowlarr, Torznab/Newznab and torrent RSS sources; external or standalone download clients (including built-in NNTP Usenet and companion Mister Download Manager CLI/Remote BitTorrent—with exact single-file selection on release grabs—& multi-connection HTTP).
  • DAT collection comparison, region/1G1R selection, and staged acquisition from an existing qBittorrent set torrent.
  • Exact duplicate audit, quarantine and restore; a preview comes before any move.
  • Preview-first renaming for DAT-verified single files already in a library, with a saved restore journal.
  • Multiple library destinations, notifications, import lists and frontend exports.
  • Game pages, a wishlist that saves games without searching, and monitoring you can switch on or off later. Monitoring guide.
  • Game soundtracks found by title or picked from your music folder, uploaded into RomM's Jukebox with exact undo. Soundtracks guide.
  • A Switch Updates & DLC report; new updates and DLC are filed inside their game's folder where RomM finds them; plus NTSC/PAL and preferred-format release preferences. Switch guide.
  • ZIP, 7z, RAR and compressed TAR downloads, read without extracting unsafe paths.
  • PS4, PS5 and PS Vita search/import formats, with explicit playback and installation limits.

Source access, available files, credentials and platform support vary. Check the result and the task history; a configured connection does not guarantee a particular game is available.

Play with Cartridge

Cartridge is the dedicated player ecosystem for self-hosted game libraries, connecting seamlessly to RomM or directly to ROMarr's embedded RomM-API backend. While ROMarr finds, verifies, and organizes your files, Cartridge provides controller-first frontends to browse, sync saves, and launch games across your screens:

Platform Client Best Fit Features & Downloads
Windows Cartridge for Windows Desktop PCs, laptops, and Windows handhelds (ROG Ally, Legion Go) Embedded RomM console player, standalone window, no external browser required. Download Portable EXE or visit BlizzHacker/Cartridge.
Xbox Cartridge for Xbox Xbox Series X|S and Xbox One consoles Native UWP/WebView2 gamepad experience, big-screen TV navigation, and EmulatorJS cores. Available on Microsoft Store (App ID: 9MXC51W17LH4) and BlizzHacker/Cartridge.
Android Cartridge for Android Retro handhelds (Odin 2, Retroid Pocket, Anbernic), Android TV, tablets, phones Gamepad-native launcher with bidirectional save-sync, rich metadata, on-demand downloads, and automated emulator handoff to RetroArch, Dolphin, PPSSPP, and NetherSX2. Download APK from Releases or visit BlizzHacker/Cartridge.

You can use Cartridge alongside your existing setup or keep using your favorite frontend (Playnite, LaunchBox, ES-DE, Pegasus). The Windows desktop app's Cartridge menu and the setup guides link to all three clients.

Community & Support

Help and documentation

Need Read
First setup and a successful import Getting started
Usenet providers, indexers and failed searches Usenet setup and troubleshooting
Docker Desktop, NAS mounts and slow library scans NAS library guide
Safely rename existing library files Preview, selection and rollback guide
Installation, Windows, backups, updates and environment variables Install guide
Plugin availability and installation ROM Hub guide
API, library routing, players and browser downloads Feature reference
Current work and requested features Roadmap
Test evidence and known validation gaps Proof notes — dated records, not a guarantee for every integration

If something fails, open an issue with your ROMarr version, install method, the action you tried, and the relevant error or log. Remove passwords, API keys and webhook URLs. Existing-install settings are changed in the UI; most connection environment variables only seed the first run.

Contribute

Bug reports, documentation fixes and integration field reports are welcome. For code changes, install the source environment, install pytest, and run python -m pytest tests/ -q. The CI workflow runs the suite and image smoke checks.

Source plugins live in ROM Hub; see its contribution guide. ROMarr's API schema is available at /api/v1/openapi.json on your own install.

Acknowledgements

Thanks to the library, emulator and preservation projects ROMarr works with, and to Radarr, Sonarr, Questarr and gamarr for ideas and familiar workflows.

Soundtracks, the Switch report, wishlist monitoring and plugin start-up hardening build on MIT-licensed work from romarrng, Copyright (c) 2026 MOVE WEIGHT.

MIT — LICENSE. ROMarr is an independent project and is not endorsed by its integrations.

About

Find, verify and organize your game library. Native Windows and Docker, DAT checks, ROM Hub plugins, and optional RomM/Cartridge integration.

Topics

Resources

Security policy

Stars

382 stars

Watchers

5 watching

Forks

Releases

Packages

Used by

Contributors

Languages