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
Official ROMarr package maintained by BlizzHacker / MOVE WEIGHT. Use ghcr.io/blizzhacker/romarr for builds supported by the ROMarr project. Forks and code reuse are welcome. Independent projects should use their own name, logo and visual identity. ROMarrNG is a separate fork, not an official ROMarr package, and is not affiliated with, endorsed by or supported by the ROMarr maintainers. Official sources and branding policy: https://github.com/BlizzHacker/romarr/blob/main/docs/OFFICIAL-DISTRIBUTION.md The *arr for games. Request a title, ROMarr searches your indexers through Prowlarr, hands the winner to your download client, and files the ROM into your game library where it can actually be played. If you run Radarr for films and Sonarr for TV, this is the missing one. ROMarr is not tied to one library: RomM, Gaseous and Retrom are all supported and chosen with a single setting. There is also a "folder" mode that writes a plain directory tree laid out by platform, which is what Batocera, RetroPie, EmulationStation, ES-DE, EmuDeck, Pegasus, Lakka, muOS and LaunchBox all read. READ THIS BEFORE YOU HIT APPLY. ROMarr reads these variables ONCE, on first start, and copies them into its own settings. After that the saved settings win and editing the variables here does nothing at all. That is deliberate -- it is what lets you change things on the Settings page without the template overriding you every restart -- but it is the opposite of how most Unraid containers behave, so get the values right the first time. To change something later, use ROMarr's own Settings page, not this template. One more thing worth getting right up front: The "Completed downloads" path must match what your download client REPORTS, character for character. ROMarr asks the client where a finished download is and then opens that path itself, so if qBittorrent says /data/completed then ROMarr needs to see /data/completed too. Check qBittorrent's Options - Downloads "Save path", or SABnzbd's Config - Folders "Completed Download Folder", and set the container path to match. If the two genuinely cannot agree, leave it and add a remap under Settings - Media Management instead. ROMarr is maintained independently of RomM, Gaseous and Retrom.

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.
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 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.
  • 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/ and dlc/ 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

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 / 5

Categories

Related apps

Explore more like this

Explore all

Links

Details

Repository
ghcr.io/blizzhacker/romarr:latest
Last Updated2026-11-22
First Seen2026-08-03

Runtime arguments

Web UI
http://[IP]:[PORT:6868]
Network
bridge
Shell
sh
Privileged
false

Template configuration

WebUIPorttcp

Port for ROMarr's web interface.

Target
6868
Default
6868
Value
6868
AppdataPathrw

ROMarr's settings, history and indexer configuration. Keep this.

Target
/config
Default
/mnt/user/appdata/romarr
Value
/mnt/user/appdata/romarr
ROM libraryPathrw

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
Completed downloadsPathrw

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
Prowlarr URLVariable

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 API keyVariable

Prowlarr - Settings - General - API Key.

Target
PROWLARR_API_KEY
Library kindVariable

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
Library URLVariable

Your library server's address. Leave empty when Library kind is folder. Example: http://192.168.1.10:8080

Target
LIBRARY_URL
Library pathVariable

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
Library usernameVariable

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
Library passwordVariable

Password for the library account. Leave empty when Library kind is folder.

Target
LIBRARY_PASSWORD
qBittorrent URLVariable

Your qBittorrent WebUI address, for example http://192.168.1.10:8080 . At least one download client is required.

Target
QBITTORRENT_URL
qBittorrent usernameVariable

qBittorrent WebUI username.

Target
QBITTORRENT_USER
qBittorrent passwordVariable

qBittorrent WebUI password.

Target
QBITTORRENT_PASS
SABnzbd URLVariable

Optional usenet client. Example: http://192.168.1.10:8080

Target
SABNZBD_URL
SABnzbd API keyVariable

SABnzbd - Config - General - API Key.

Target
SABNZBD_API_KEY
NZBGet URLVariable

Optional usenet client. Example: http://192.168.1.10:6789

Target
NZBGET_URL
NZBGet usernameVariable

NZBGet control username.

Target
NZBGET_USER
NZBGet passwordVariable

NZBGet control password.

Target
NZBGET_PASS
Download categoryVariable

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
PUIDVariable

User ID that owns the ROMs ROMarr writes. 99 is Unraid's nobody. Match whatever your library app uses.

Default
99
Value
99
PGIDVariable

Group ID that owns the ROMs ROMarr writes. 100 is Unraid's users. Match whatever your library app uses.

Default
100
Value
100
TZVariable

Timezone, used for timestamps in history and logs. For example America/Chicago.

Default
Etc/UTC
Value
Etc/UTC
Log levelVariable

INFO, or DEBUG when you are filing a bug report.

Target
LOG_LEVEL
Default
INFO
Value
INFO