ROMarr
Docker app from UnraidUser-7237142946's Repository
Official ROMarr package maintained by BlizzHacker / MOVE WEIGHT.
Requirements
A running Prowlarr, at least one download client (qBittorrent, SABnzbd or NZBGet), and somewhere to put the ROMs -- either RomM, Gaseous or Retrom, or a plain folder.
At least one download client is genuinely required, not merely recommended: a release found with no client that speaks its protocol is ranked and then refused.
Overview
Readme
View on GitHub
ROMarr

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

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. |
| Chat with your own model about your library | Hub → Chat Agent | Ollama, an OpenAI-compatible endpoint or an Anthropic key. Searches, explains refusals and finds set gaps; asks before grabbing or changing Wanted. How it works. |
| 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 | ![]() |
| Windows Desktop App | Portable x64 WebView2 window, tray host, Cartridge player menu, and 1,220-entry Emulator Hub | ![]() |
| Android App (Mobile & Handhelds) | Bundled Chaquopy server plus HTTPS remote profile switching over mobile touch UI | ![]() |
| Android Slide-Out Drawer | Touch navigation drawer with expandable hub sections and integrated Color Changer | ![]() |
| ROMarr.app Website | Project landing page synced with real scored search results and live accent swatches | ![]() |
| Sign-In & OIDC SSO | Built-in password/API-key authentication alongside external SSO providers such as Authentik | ![]() |
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) |
|---|---|---|---|
![]() |
![]() |
![]() |
![]() |
Library Discovery, Confined Plugins & Device Sync
| Feature | Preview |
|---|---|
| Library Overview — 76,056 files on disk, platform pills, genre/region/decade filters, and cover grid | ![]() |
| Discover Shelf — 42,210 metadata-matched games from your library with top-rated, hidden-gem, and franchise filters | ![]() |
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) |
![]() |
| Device Fleet & 1G1R Planner — Non-destructive Igir sync plans and frontend exports for ES-DE, RetroPie, Batocera, Steam Deck, and Argosy | ![]() |
Tour more views: MCP AI Connector, Device Cards, Emulator Hub, Collections, Friends & System Telemetry
| View | Preview |
|---|---|
| Device Profiles & Handheld Cards | ![]() |
| AI Agents (MCP) Connector | ![]() |
| Emulator Hub & Cartridge Setup | ![]() |
| Ecosystem (Igir v5.8.0 & Backends) | ![]() |
| Collections & Set Torrents | ![]() |
| Statistics & Indexer Telemetry | ![]() |
| Friends & Federation | ![]() |
| Browse Shared Friend Shelf | ![]() |
| Import Lists & Storefront Connectors | ![]() |
| Storefront Session Token Modal | ![]() |
| Activity History | ![]() |
| Notification Providers | ![]() |
| Library Backends | ![]() |
| System Health & GG Requestz | ![]() |
| Scheduled Tasks | ![]() |
| Live Process Logs | ![]() |
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.
- Base game, update and DLC handling for PlayStation 3/4/5, PSP, Vita, 3DS, Wii U, Switch, Xbox 360 and PC: search tells packs, updates and DLC apart, requests can ask for the update and DLC too, and imports file
<Title>/,update/anddlc/the way RomM reads them. Updates and DLC 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
- Discord: Join the ROMarr Discord server for release help, plugin tips, and troubleshooting.
- Open Collective: Back ROMarr on opencollective.com/romarr (contributors badge).
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.
Batch decompression hands disc images to Compressatorium by pacnpal over its HTTP API, through the preinstalled Compressatorium plugin; no Compressatorium code is included.
ScreenScraper and SteamGridDB metadata are ported from MIT-licensed RetroArr, Copyright (c) 2026 RetroArr.
Demo and executable refusals, Usenet minimum age and retention, and complete-edition detection follow the behaviour of Gamarr; no Gamarr code is included.
Signed webhooks, notification links and NZB detection in Torznab feeds follow the behaviour of Questarr; no Questarr code is included.
Standalone direct HTTP and BitTorrent downloads use Mister Download Manager by anefzaoui (GPL-3.0-or-later), run as a separate program or over its Remote HTTPS API, with its settings in the preinstalled Mister Download Manager plugin; no Mister Download Manager code is included.
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.
Media gallery
1 / 5Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/blizzhacker/romarr:latestRuntime arguments
- Web UI
http://[IP]:[PORT:6868]- Network
bridge- Shell
sh- Privileged
- false
Template configuration
Port for ROMarr's web interface.
- Target
- 6868
- Default
- 6868
- Value
- 6868
ROMarr's settings, history and indexer configuration. Keep this.
- Target
- /config
- Default
- /mnt/user/appdata/romarr
- Value
- /mnt/user/appdata/romarr
Where finished ROMs are filed. Point the left-hand side at the same share your library app reads. The right-hand side must match the Library path variable below.
- Target
- /roms
- Default
- /mnt/user/roms
- Value
- /mnt/user/roms
Your download client's completed folder. The RIGHT-hand side must be the path your client reports, character for character -- ROMarr asks the client where a finished download is and then opens that path itself. qBittorrent shows it under Options - Downloads as Save path; SABnzbd under Config - Folders as Completed Download Folder. If they cannot be made to agree, add a remap under Settings - Media Management instead.
- Target
- /downloads
- Default
- /mnt/user/downloads
- Value
- /mnt/user/downloads
How ROMarr finds releases. Use your server's LAN address, not localhost -- localhost inside this container is this container. Example: http://192.168.1.10:9696
- Target
- PROWLARR_URL
Prowlarr - Settings - General - API Key.
- Target
- PROWLARR_API_KEY
Which game library to file into: romm, gaseous, retrom, or folder. Use folder for Batocera, RetroPie, ES-DE, EmuDeck, Pegasus, Lakka, muOS or LaunchBox -- those read a plain directory tree and need no URL or account.
- Target
- LIBRARY_KIND
- Default
- romm
- Value
- romm
Your library server's address. Leave empty when Library kind is folder. Example: http://192.168.1.10:8080
- Target
- LIBRARY_URL
Where ROMs are written, as seen INSIDE this container. This is the right-hand side of the ROM library mount above, not the host path. Leave it as /roms unless you changed that mount.
- Target
- LIBRARY_PATH
- Default
- /roms
- Value
- /roms
Use a dedicated account, not your admin one. All ROMarr needs is permission to trigger a rescan. Leave empty when Library kind is folder.
- Target
- LIBRARY_USERNAME
Password for the library account. Leave empty when Library kind is folder.
- Target
- LIBRARY_PASSWORD
Your qBittorrent WebUI address, for example http://192.168.1.10:8080 . At least one download client is required.
- Target
- QBITTORRENT_URL
qBittorrent WebUI username.
- Target
- QBITTORRENT_USER
qBittorrent WebUI password.
- Target
- QBITTORRENT_PASS
Optional usenet client. Example: http://192.168.1.10:8080
- Target
- SABNZBD_URL
SABnzbd - Config - General - API Key.
- Target
- SABNZBD_API_KEY
Optional usenet client. Example: http://192.168.1.10:6789
- Target
- NZBGET_URL
NZBGet control username.
- Target
- NZBGET_USER
NZBGet control password.
- Target
- NZBGET_PASS
What ROMarr labels its own downloads with, so they stay distinguishable in a client you also use for other things. The category does not have to exist in the client beforehand.
- Target
- QBITTORRENT_CATEGORY
- Default
- romarr
- Value
- romarr
User ID that owns the ROMs ROMarr writes. 99 is Unraid's nobody. Match whatever your library app uses.
- Default
- 99
- Value
- 99
Group ID that owns the ROMs ROMarr writes. 100 is Unraid's users. Match whatever your library app uses.
- Default
- 100
- Value
- 100
Timezone, used for timestamps in history and logs. For example America/Chicago.
- Default
- Etc/UTC
- Value
- Etc/UTC
INFO, or DEBUG when you are filing a bug report.
- Target
- LOG_LEVEL
- Default
- INFO
- Value
- INFO





























