ROMarr

The *arr for games.

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

Install · First setup · Plugins · Roadmap · Releases

What can I use it for?

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. A bulk, in-place rename planner for existing libraries is on the roadmap.

Install

Choose a method

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; torrent, Usenet and plugin download clients.
• 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.
• 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 for Windows and Cartridge for Xbox are optional players for a RomM library. Choose the app for your device. ROMarr manages acquisition and imports; Cartridge connects to RomM to browse and play. You can keep using your existing frontend instead. The Windows app's Cartridge menu and the Setup Guide link to both.

Help and documentation

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.

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

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