BlizzHacker/romarr

docker run -d --name romarr --restart unless-stopped \
  -p 6868:6868 -v /srv/romarr/config:/config \
  ghcr.io/blizzhacker/romarr:latest

Open http://localhost:6868, set a password, and connect your indexers. Prefer something else? Docker Compose · Proxmox LXC one-liner · Home Assistant add-on · From source

Your library	Plugins from ROM Hub
Stats and your shelf	Friends and shared libraries

Take the full tour →

ROMarr is MIT-licensed and contributions are welcome, from a typo fix to a whole new download client.

• Add a game source without touching ROMarr: write a ROM Hub plugin.
• Integrate your app through the REST API. Every route is described at /api/v1/openapi.json on your install.
• Pick up an issue: open issues. Questions and ideas are welcome there too.
• Run it locally: python -m romarr from a clone, and pytest runs 2,300+ tests. See Development.

Move Weight
└─ Yarr.It ................ one front door for a self-hosted media library
   └─ Cartridge ........... tools for self-hosting a retro game library
      └─ ROMarr ........... you are here
         └─ ROM Hub ....... ROMarr's plugin engine

ROMarr runs perfectly well on its own; nothing above it is required.

• 🎲 Backlog roulette. Can't choose? Stats → Shelf → Pick my next game draws one from your Shelved or Playing games.
• 🛡️ Virus scanning before import. Point ROMarr at ClamAV and every finished download is scanned; an infected release is refused, blocklisted and replaced automatically.
• 🔗 Integration API that actually works. External apps such as Cartridge frontends can request games and poll their status, and retries never download twice.
• 🖥️ Proxmox installer fixed for every CPU. The one-line LXC installer now picks the right template for your host (amd64 or arm64).

• How it works
• The tour — every feature, what it is for, and what it looks like
• Requirements
• Installation — Docker · Docker Compose · Proxmox LXC · Home Assistant · Source
  • The full install guide — every variable, backup, upgrade, rollback, troubleshooting
• Signing in
• Configuration
• Usage
• Plugins
• Multiple libraries
• Troubleshooting
• Cartridge ecosystem

One request, end to end:

you: "Chrono Trigger, SNES"
  │
  ▼
SEARCH     every indexer at once, via Prowlarr or directly
  │          two queries per source — the bare title and the qualified one —
  │          because indexers match whole strings and recall wins
  ▼
SCORE      every release, with written reasons
  │          + seeders, + right region, + carries a .smc, + verified dump
  │          − hack/beta/repack, − wrong platform named, − too big to be real
  ▼
GRAB       the winner goes to whichever client speaks its protocol
  │          torrent → 13 daemons, 8 debrid services, or a watched folder
  │          usenet  → SABnzbd/NZBGet/NZBVortex, or a watched folder
  │          ROM site → a plain GET, or a real browser click where the site
  │                     has no fetchable URL
  ▼
IMPORT     within a minute of completion, on the clock
  │          the actual ROM picked out of the archive (zip/7z/rar, zip-slip safe)
  │          multi-track discs kept together as a set
  ▼
VERIFY     checksummed against your No-Intro / Redump DATs
  │          verified · bad dump · unknown — and only bad dumps are refused
  ▼
FILE       into RomM / Gaseous / Retrom / Gameyfin / a plain folder
  │          per-platform routing if you run more than one
  ▼
RESCAN     your library server is told; the game appears with art

Nothing in that pipeline needs you after the first line — and with lists, connected accounts and RSS, it doesn't even need the first line.

Everything below is real: each screenshot comes from the maintainer's production install (166,578 games, ten live indexers), and every claim links to its evidence in docs/PROOF.md.

Add New takes a title and a platform and does the whole pipeline. Interactive Search is for when you want to see the machine think: every release your indexers returned, scored, with the reasoning written next to it, a link to the release's page on its indexer, and a Grab button for when you disagree. A manual grab flows through the same queue and history as an automatic one.

The scoring knows things a film downloader can't: that a 40GB "SNES" result is a romset or a PC port (every platform declares a hardware ceiling), that "Super Nintendo Entertainment System" containing "Nintendo Entertainment System" is a trap (longest alias wins, unknown platforms are refused, never guessed), and that a Wii Virtual Console WAD is not a Genesis cartridge.

The one thing no other *arr can do. There is no canonical hash for a movie — but No-Intro (cartridges) and Redump (discs) publish the CRC32/MD5/SHA1 of every known-good dump. ROMarr checksums every import against your DATs:

• verified — byte-for-byte the published dump. Shown as [!] everywhere.
• bad dump — right size, wrong hash. The case worth catching; refused unless you explicitly force it.
• unknown — not in your DAT. Not treated as bad: homebrew, translations and romhacks live here and import without ceremony.

Copier headers are handled (the reason naive hashers match nothing on NES/SNES), discs verify per-track, and a verified dump automatically upgrades an unverified copy — the only upgrade rule in this category that is a fact about bytes rather than a taste in bitrates.

Six jobs run without you: completed downloads import every minute; the Wanted list is re-searched every 12 hours with a per-title backoff ladder (4h → 7 days, so a game that isn't dumped yet doesn't get your tracker account banned); indexer RSS feeds are watched hourly in between, so a release that appears an hour after you asked is grabbed within the hour; lists sync every 6; dead downloads are retired every 15 minutes (below); and once a day ROMarr asks GitHub if a newer version exists — and tells you, because an *arr that updates itself is an *arr that restarts mid-import. Every RSS match goes through the same scorer as a search: the feed can never grab what a search would refuse. Intervals are editable live; zero disables a job.

A stalled torrent used to be a loop. The Blocklist existed, nothing ever added to it, and best_release is deterministic — so pulling the dead torrent out of your client and waiting for the next sweep scored the same results the same way and grabbed the same dead file again.

Now a download the client refused, one that finished with no ROM in it, or one still unfinished past stalled_timeout_minutes (default three hours) is blocklisted with the reason attached, the game goes back on Wanted, and the next best release is grabbed in its place. Capped at three replacement grabs per sweep, because each one costs a full indexer search and twenty at once is how a tracker decides you are a scraper.

What is deliberately not blocklisted: no download client configured. That failure is your install's, not the release's — and a blocklist full of good torrents blocked because a client was missing is worse than no blocklist at all.

And a request you no longer want can now simply be dropped: Remove on any Wanted row, or DELETE /api/v1/wanted/missing. Until now the only way off that list was an import, so a typo went on costing an indexer search on every sweep and every RSS pass, forever, for a game that does not exist.

Point ROMarr at a ClamAV daemon (Media Management → Scan downloads with ClamAV, address tcp://clamav:3310 or a socket path) and every finished download is streamed to it before anything is imported. An infected one is refused with the signature named, and counted as the release's fault, so the blocklist retires it and the next best release is grabbed. While clamd cannot be reached, finished downloads wait rather than going in unscanned. System → Status shows whether it answers.

One limit is clamd's own: it refuses a stream longer than its StreamMaxLength. Such a file is imported unscanned and logged by name, since refusing it would leave every large disc image unimportable. Raise the limit in clamd.conf if you want those scanned too.

Paste a numbered "top 100" article exactly as you copied it — rank numbers, # comments and Title<TAB>platform lines all parse. Point at a URL that re-syncs on the clock. Every title feeds Wanted once, ever — a ledger per list means a fulfilled game is never re-downloaded by its own list.

Connect the stores you already own games on, two ways:

An earlier version of this README claimed EA, Battle.net and Epic "have no API" and could not be connected. That was wrong, and Playnite and LaunchBox were the standing counter-example — they have pulled owned libraries from all three for years. Each does have a web API; what none of them has is an application key you can request, so they authenticate with the browser session you already have. ROMarr now uses exactly the same routes Playnite does: Epic's launcher OAuth, EA's entitlements API, and Blizzard's own account games list. One click opens the page, one paste connects it, and Epic's is a one-time code traded for a refresh token so later syncs are silent.

The local scan is a complement, not a substitute: it catches everything installed regardless of store, and needs no credential at all.

Nintendo is the one honest exception: no web API, and nothing written to a PC to read. It says so on the page.

Load a DAT, and ROMarr can answer "what does a complete set look like, and how far off am I?" — full sets or one-game-one-ROM with your region ladder, diffed against what's actually on disk, acquired in resumable batches. A 3,000-title set is not an all-or-nothing operation: pause it, resume it, retry the failures.

Click any tile: playing / completed / shelved, a 0–10 rating, and notes. Wanted and owned are deliberately derived (from the wanted list and the library) so nothing drifts. Discover adds the three storefront shelves — popular, new, upcoming — browsable onto a Request button, and the Stats page turns the history into numbers:

Discord, Slack, Telegram, Pushover, Gotify, ntfy, plain webhooks, and Apprise (which unlocks ~100 more). Every other tool sends "Grabbed: Chrono Trigger". ROMarr's message carries what the scorer weighed — +50 verified good dump [!], +40 region usa, +40 30 seeders — so you can tell a good pick from a lucky one without opening the UI.

Auth is on by default (password + optional TOTP, API keys, ForwardAuth SSO behind Authentik/Authelia); native HTTPS via ROMARR_SSL_CERT/KEY; the Logs page tails the actual process log live; backups strip credentials before they leave; Prometheus metrics and an OpenAPI spec for everything; remote path mapping for clients on other hosts; and history, wanted, the download queue, shelf and settings all survive restarts. Prowlarr's API keys never reach a browser or a log, archives cannot zip-slip out of the library root, and an existing ROM is never silently overwritten.

docs/INSTALL.md is the full guide — every install path, every environment variable with its default and what a wrong value does, where your data lives, backup, upgrade, rollback, and a troubleshooting section built from failures that actually happened. What follows is the short version.

Enough to see the UI. No library or downloads volume on purpose — nothing can land in the wrong place while you are still deciding where things go.

docker run -d --name romarr \
  --restart unless-stopped \
  -p 6868:6868 \
  -e PUID=1000 -e PGID=1000 -e UMASK=002 -e TZ=Etc/UTC \
  -v /srv/romarr/config:/config \
  ghcr.io/blizzhacker/romarr:latest

Open http://localhost:6868 and set a password.

--restart unless-stopped is not decoration: without it ROMarr does not come back after a host reboot, and the first sign is a week of missed scheduled searches. Use an absolute path for /config — Docker Engine below 23 rejects a relative bind source as an invalid volume name.

To actually import anything, use compose.

Upgrading from 0.6.x? The default port changed from 7878 to 6868. 7878 is Radarr's port, and running both is the normal case rather than the exception, so ROMarr was colliding with it on a default install. 6868 sits in the gap the *arr family left between Bazarr (6767) and Whisparr (6969).

If you pinned the port yourself — ROMARR_PORT, or a 7878:7878 mapping — nothing changes until you remove the pin. If you relied on the default, update your port mapping to 6868:6868, or set ROMARR_PORT=7878 to keep the old one.

Images are published for linux/amd64, linux/arm64 and linux/arm/v7. The armv7 leg is built in CI and has never been booted by the maintainer — see INSTALL.md.

The recommended install. A docker-compose.yml with every setting commented ships in the repo:

mkdir -p /srv/romarr && cd /srv/romarr
curl -O https://raw.githubusercontent.com/BlizzHacker/romarr/main/docker-compose.yml
printf 'ROMARR_ROMS=/mnt/roms\nROMARR_DOWNLOADS=/mnt/downloads\n' > .env
docker compose up -d

Those two paths have no defaults and compose refuses to start without them. That is deliberate: Docker creates a missing bind-mount source, so a placeholder like /path/to/roms produced a container that started, reported healthy, and filed ROMs into a directory no library server had ever scanned — with every indicator green. Everything else in the file can be wrong and the Settings page will say so; those two could only be wrong silently.

bash -c "$(curl -fsSL https://raw.githubusercontent.com/BlizzHacker/romarr/main/proxmox/ct/romarr.sh)"

It waits for /api/health to answer before claiming success, refuses to deploy a build without romarr/auth.py, and prints the version it installed. Update later with proxmox/ct/update.sh, which reports the version it moved you from and to and puts the old build back if the new one will not start.

Settings → Add-ons → Add-on Store → ⋮ → Repositories, add https://github.com/BlizzHacker/romarr, install ROMarr. Options set on the add-on page become ROMarr's environment — see homeassistant/romarr.

git clone https://github.com/BlizzHacker/romarr.git && cd romarr
pip install -r requirements.txt
cp .env.example .env          # edit it
set -a; . ./.env; set +a
python -m romarr

PUID/PGID set the ownership of imported ROMs — use the same numeric IDs as your library application. UMASK=002 makes new files group-writable. Only /config is chowned, recursively; existing library and download files are never chmod'd or chown'd.

The one rule that catches everyone. Environment variables seed the configuration on the first run. After that the Settings page is the authority and the environment is ignored — so editing QBITTORRENT_URL in compose and restarting changes nothing, with no error and no warning. Change it on the Settings page instead. Why, and which variables are exempt.

ROMarr requires a credential. There is no open mode you can fall into by forgetting to configure something.

The first time you open the web UI, it asks you to set a password. That is the whole of first-run setup — there is no key to go and find first. Once set, the install is claimed, that screen becomes a normal sign-in, and the password survives restarts.

Your browser then holds a signed session cookie, so the key is never kept in the page.

To skip the setup screen entirely, claim the install from its environment before it starts. This is what a container template should do, because it leaves no window in which an unclaimed ROMarr is reachable:

-e ROMARR_PASSWORD=choose-something-long

*For scripts and other arrs, use the API key. One is generated on first run and shown under Settings → General; set ROMARR_API_KEY to pin it to a value you choose. Present it any of three ways:

curl -H "X-Api-Key: $KEY"          http://localhost:6868/api/v1/game
curl -H "Authorization: Bearer $KEY" http://localhost:6868/api/v1/game
curl "http://localhost:6868/api/v1/game?apikey=$KEY"

An API key also signs a browser in, via Use an API key instead on the sign-in screen — which is how you get back in if the password is lost: set ROMARR_API_KEY, restart, and sign in with it.

Two-factor (TOTP) is enrolled from Settings → General and applies to interactive sign-in. It deliberately does not gate the API key: a script cannot be prompted, and a key is already a high-entropy secret.

ROMARR_AUTH=disabled means anything that reaches the port is in, including a request that bypassed your proxy. If a proxy already authenticates, prefer ROMARR_AUTH=forward, which keeps the proxy as the authority but verifies the request actually came through it.

¹ Not required for LIBRARY_KIND=folder, which needs only LIBRARY_PATH.

Legacy ROMM_* variables are still read, so existing installs need no changes.

folder covers Batocera, RetroPie, Recalbox, EmulationStation, ES-DE, EmuDeck, Pegasus, Lakka, muOS, ArkOS, LaunchBox, Playnite and Steam ROM Manager — they read ROMs from a directory laid out by platform, which is what ROMarr writes. No URL, no account, no API key:

LIBRARY_KIND=folder
LIBRARY_PATH=/mnt/roms

58 platforms. The bar for inclusion is a real play route — a core in RomM's base EmulatorJS map, or one installed on a stream server.

Cartridge — NES, Famicom, Famicom Disk System, SNES, Super Famicom, Game Boy / Color / Advance, N64, Genesis / Mega Drive, Sega 32X, Master System, Game Gear, Atari 2600 / 5200 / 7800, Lynx, Jaguar, TurboGrafx-16, SuperGrafx, ColecoVision, Intellivision, Vectrex, WonderSwan / Color, Neo Geo Pocket / Color, Neo Geo AES / MVS, Arcade, Virtual Boy, Nintendo DS, Nintendo 3DS.

Disc — PlayStation, PlayStation 2, PSP, Saturn, Sega CD / Mega-CD, Dreamcast, GameCube, Wii, 3DO, Philips CD-i, PC-FX, TurboGrafx-CD / PC Engine CD, Amiga CD32, Neo Geo CD, Atari Jaguar CD.

Home computer — Commodore 64 / 128 / VIC-20, Amiga, Amstrad CPC, ZX Spectrum, MSX / MSX2, Sharp X68000, MS-DOS.

For Arcade, Neo Geo and DOS the archive is the ROM — MAME, FBNeo and dosbox_pure open the .zip themselves and expect its internal layout, so ROMarr imports it whole instead of unpacking a romset into loose chip dumps.

Disc images are multi-file. A .cue is a few hundred bytes of text naming tracks, and importing it on its own gives you a library entry with a title, a cover and no game — so ROMarr reads the sheet, takes every track it names, and files the set as a directory, which is the layout RomM's scanner treats as one multi-part ROM. .7z and .rar are read as well as .zip, because that is what disc releases actually ship as.

System → Platforms answers this per platform for your own install. There are four routes and the last one is not a failure:

"In the browser" is four different programs, and which of them can open a row is decided by the file, not the platform. GET /api/v1/players lists them and GET /api/v1/play?file=…&platform=… answers for one file.

All four are on by default and any of them can be turned off with ROMARR_PLAYERS, best first. Turn Ruffle off if your RomM runs with DISABLE_RUFFLE_RS, so ROMarr stops promising a button that will not be there. Turn Emularity off if you would rather nobody was sent off your install to play something. Where more than one player can open a file, ROMarr offers them in your order and names the reason for each; where one could and is not configured, it says which setting fixes that rather than saying nothing.

A library server can hold a row for a game it does not have the bytes for — RomM calls it missing_from_fs, and on the maintainer's install that is 94,428 of 166,548 rows. Asking for the content of one returns 404.

Nothing plays those. Nothing streams them. Nothing downloads them either, which is why reporting them as "download only" was worse than saying nothing: it named a route that 404s. ROMarr says the file is not here, says what would play it once ROMarr has fetched it, and keeps the Archive.org route where it applies — because that is somebody else's copy, and it is the reason a catalogued row was catalogued in the first place.

A Moonlight host is a desktop, not a platform router, and ROMarr says so. Wolf, Sunshine and Steam Headless all answer /serverinfo with no credential, so ROMarr can always tell you the host is alive. What they cannot be asked is what a given application will open — there is no endpoint for it in any of the three. So a host earns a platform a stream route only when its app list names an emulator for exactly one machine (PCSX2, Dolphin, flycast). A RetroArch or a Steam earns nothing, because a RetroArch with no cores and a RetroArch with forty look identical from outside the container. And pairing is manual by design: the PIN is generated by your Moonlight client, on your device, so ROMarr can be the box you type it into and nothing more. The whole account is in docs/design/streaming-hosts.md, including a list of what has never been run against real hardware.

What still cannot play, and why. ROMarr says this per platform on the Platforms page rather than making you find out at the point of clicking play.

• Atari Jaguar CD — no emulator plays it. virtualjaguar is the only Jaguar core in libretro and declares j64|jag|rom|abs|cof|bin|prg: cartridges, no cue, no chd. MAME's own source marks its jaguarcd driver MACHINE_NOT_WORKING. Jaguar cartridges play fine.
• Sharp X68000 — px68k is installed and needs Sharp's iplrom.dat and cgrom.dat, which you supply from your own hardware. There is no free equivalent the way C-BIOS exists for MSX.

Everything else on the list plays.

Everything else plays. Where a stream server has the core but not the firmware it says that, because a core with no BIOS does not fail loudly: it draws an error screen and streams it at a perfectly healthy 30 fps.

Nothing is refused on these grounds — cataloguing a platform you play elsewhere is a legitimate thing to want. ROMarr tells you which route applies before the grab instead of leaving you to find out at the point of clicking play, and where a platform has no player it says what would fix it. If your stream server has the core but not the firmware, it says that, because a core with no BIOS does not fail loudly: it draws an error screen and streams it at a perfectly healthy 30 fps.

Library → Add New. Enter a title, pick a platform, click Search & Grab. ROMarr searches, scores, grabs and imports.

Library → Interactive Search. Every release is returned scored, with the reasoning shown:

+40  20 seeders
+60  carries a Super Nintendo ROM extension
+25  region (USA)
-120 looks like a hack, beta or repack ('hack')

Rejected releases are listed greyed out with the reason. Grab whichever you want — a manual grab goes through the same queue, history and wanted handling.

Download URLs are never returned to a client: Prowlarr's downloadUrl carries its API key, so releases are grabbed by the id issued with the search and the URL is resolved server-side.

GG Requestz pushes approved requests to ROMarr. It is not a rom-hub webhook command inside the ROMarr container. Open System → GG Requestz requests to build the exact setting, or configure this in the GG Requestz container:

REQUEST_WEBHOOK_URL=http://romarr:6868/api/v1/webhook/ggrequestz?apikey=<ROMARR_API_KEY>

http://romarr:6868 works when both containers share a Docker network. On Unraid or separate networks, replace it with ROMarr's LAN or HTTPS URL as seen from inside GG Requestz. Restart GG Requestz after changing its environment.

GGREQUESTZ_URL goes the other direction: it only lets ROMarr show and ping the GG Requestz page. A green status there proves the page is reachable; it does not prove the outbound webhook is configured.

GG Requestz 1.5 and newer dispatches when a request becomes approved, not when a pending request is first submitted. Enable request.auto_approve or approve the request manually. ROMarr answers an accepted request with HTTP 202; an invalid event or unknown platform receives HTTP 422 so GG Requestz records a real delivery failure instead of treating the request as sent.

The finished webhook URL contains ROMarr's API key. Treat it like a password, keep it on a trusted Docker network or HTTPS, and do not paste it into public logs.

Hub → Plugins. ROMarr's sources are ROM Hub plugins — install, enable and disable them from the UI.

Install ROM Hub into ROMarr's own environment to enable the tab. On the Proxmox LXC or a source install that is /opt/romarr/.venv, and it needs git:

apt-get install -y git
/opt/romarr/.venv/bin/pip install "rom-hub @ git+https://github.com/BlizzHacker/rom-hub@master"
systemctl restart romarr

A pip install into the system Python or into a different venv is invisible to ROMarr.

Plugins requiring an API key (e.g. RetroAchievements) are marked in the UI.

Plugins are third-party and sandboxed by the host — install only ones you trust.

API: GET /api/v1/hub/plugins, POST /api/v1/hub/plugin (install, enable, disable, uninstall).

Sites that serve files over plain HTTP have no torrent and no NZB, so ROMarr fetches them itself. Two download clients on the Download Clients page cover it, and a plugin declares which one its site needs:

Why the browser mode exists, and what it is not. A few sites have no fetchable URL at all — Vimm's Lair's download is a POST carrying a mediaId, and the GET-shaped URL that appears in two published catalogues returns HTTP 400, because it was guessed rather than observed. The only honest way to fetch from a site like that is to be on the page: a real headless Chromium opens the real page and clicks the real download control, so every header that goes out, Referer included, is one the browser genuinely produced. That is automating a user action. It is not a bot-detection bypass, and it will not become one:

• CAPTCHAs are not answered.
• A Cloudflare (or any other) challenge ends the fetch, by name, with the reason reported to you.
• No stealth plugin, no fingerprint spoofing, no navigator.webdriver patching, no forged headers, and no signing in anywhere.
• robots.txt is honoured including Crawl-delay, one file is fetched at a time, 429 and 503 are waited out, and a 403 stops that site for good.

A site that can only be downloaded from by doing one of those is reported as unavailable, with the reason, and its plugin stays catalogue-only. That is the finished answer for such a site. tests/test_site_downloader.py asserts the absence of the evasion machinery, so the promise fails the build rather than eroding quietly.

Installing the browser mode. It is deliberately not a ROMarr dependency — Chromium is 867MB and 236 packages on Debian, which is not something to put in a 1GB container that will never use it. Direct downloads work without any of this, and the Download Clients page says so rather than failing obscurely.

# On the machine that will run the browser:
pip install playwright && playwright install --with-deps chromium

Running ROMarr in Docker or Unraid? The default image is Alpine (musl), and Playwright publishes only glibc wheels, so pip install playwright inside it fails with "No matching distribution found" and always will. Use the browser edition instead, which is the same app on Debian with the Playwright client (and no Chromium) preinstalled:

ghcr.io/blizzhacker/romarr:browser

On Unraid, set the container's Repository to that, or pick the browser tag in the template. Then run the browser itself in a second container and set Browser Host to it:

docker run -d --name playwright --restart unless-stopped -p 3000:3000 \
  --init --ipc=host mcr.microsoft.com/playwright:v1.62.0-noble \
  npx -y playwright@1.62.0 run-server --port 3000 --host 0.0.0.0
# Browser Host: ws://<that-host>:3000

The client and the server must be the same Playwright version (the image ships 1.62.0).

Then either leave Browser Host blank to launch Chromium beside ROMarr, or — better for a small container — run the browser somewhere else:

# On the browser's host:
playwright run-server --host 0.0.0.0 --port 3000

and point ROMarr at ws://<host>:3000. The driver runs there, so the finished file streams back over the same socket and the two need no shared directory. (An http:// endpoint — a bare chromium --remote-debugging-port — works too, but that Chromium saves onto its own disk, so it needs a directory both can see plus a remote path mapping.)

API: GET /api/v1/downloadclient/browser reports whether the lane can run here and why not when it cannot.

Proof: python scripts/prove_site_download.py fetches the same Archive.org file through both modes and checks the SHA-256 matches.

Settings → Libraries. Each entry has its own address, credentials and filesystem path; one is marked default.

Routing is by platform — a library with platform rules receives only those platforms, everything else goes to the default. "N64 goes to Retrom" is one row on that page rather than a second ROMarr instance.

Each server needs its own path as ROMarr sees it. The Libraries page flags a server that answers while its path is missing locally — usually a volume that was never mounted into ROMarr.

Gaseous has no scan trigger in its API and picks up files through its own background tasks (TitleIngestor every minute over the Import directory; LibraryScan every 1440 minutes over library paths). Point that library's path at Gaseous's Import directory, or lower the LibraryScan interval.

RomM requires the account ROMarr uses to have permission to run tasks, or the rescan is refused with a 403.

The full list, including every way an install can fail to start, is in docs/INSTALL.md. The ones people hit most:

"remote_path_mappings": [
  { "remote": "/downloads", "local": "/mnt/downloads" }
]

Longest matching prefix wins. The log records both the path the client reported and what ROMarr resolved it to.

• Prowlarr API keys are never returned to a browser or written to a log.
• Archive entries resolving outside the library root are dropped (zip-slip).
• Existing ROMs are never silently overwritten.
• Use a dedicated library account, not an administrator one.

python -m pytest tests/ -q

Release selection, ROM identification and archive-entry safety are pure functions and are tested directly.

An honest map of what is solid, what is thin, and where a contribution lands hardest. 1,170+ tests run on every push; the numbers below are per area, and "tested against fakes" means the protocol conversation is asserted but no live server was in the loop.

Where help lands hardest: field reports for the medium-confidence download clients and library backends; a .NET owner for the contrib plugins; Home Assistant users for the add-on; DAT sources for platforms beyond No-Intro/Redump coverage; and issues — a report with a log line is usually fixed the same week. Open issues: github.com/BlizzHacker/romarr/issues.

ROMarr is the acquisition component of Cartridge, a self-hosted retro-gaming stack by MoveWeight.

Brand and naming: BRAND.md.

ROMarr is part of a family of open, self-hostable projects built by Move Weight. Use one, or plug them all together.

If one of these is useful to you, a ⭐ on GitHub is the easiest way to help.

Questarr by Doezer (GPL-3.0). Several ROMarr features landed after Questarr proved the demand for them in a game *arr: the scheduled search / RSS-sync clock, per-game status, ratings and notes, the stats page, the wider download-client roster (Transmission, Deluge, rTorrent, Synology Download Station), native SSL, and Home Assistant packaging. No code was taken — Questarr is TypeScript and ROMarr is Python — but the case for those features was made there first, and saying so costs nothing. As of August 2026 every capability on their feature list and published roadmap has a ROMarr equivalent, and the acquisitions here come with the one thing no title-parsing pipeline can add: a checksum against the published dump.

gamarr by JeremiahM37 (MIT). Several features here exist because gamarr had them first and its README made the case for them plainly: the blocklist, release profiles, quality profiles, notification connections, tags, manual import, and Prometheus metrics. No code was taken — gamarr is Go and ROMarr is Python, and every implementation here was written from scratch — but the feature set was informed by theirs, and saying so is the least that is owed.

Radarr and Sonarr, for the shape of the whole category: indexer and download-client registries rendered from field definitions, quality and release profiles, remote path mappings, and Manual Import.

ROMarr acquires ROMs and files them — nothing more. It stores no library, serves no player, publishes no DAT, indexes no tracker, runs no download. Every one of those is somebody else's work, and without them there is nothing here to automate. The same list, with an install command for each where one exists, is on the app's System → Ecosystem page — because respect that is also a convenience is worth more than a paragraph.

Library servers — where your games actually live: RomM (romm.app), Gaseous, Retrom, Gameyfin. RomM in particular is the project ROMarr was built beside, and its EmulatorJS core map is the basis of the playability routing.

Players — how a library is played: EmulatorJS (emulatorjs.org), RetroArch / libretro, Moonlight, Wolf, Sunshine, Steam Headless, ES-DE, Batocera, Playnite, LaunchBox.

Acquisition — the rest of the request pipeline: GG Requestz by XTREEMMAK (the Overseerr of games — ROMarr takes its requests), Prowlarr, and qBittorrent.

Preservation — what makes verification real at all: No-Intro and Redump, whose DATs are the only reason ROMarr can say a file is correct rather than just plausible.

MIT — see LICENSE.

Unofficial. Not affiliated with or endorsed by the RomM, Gaseous or Retrom projects.