Skip to content

Installation

BlizzHacker edited this page Nov 17, 2026 · 1 revision

Installation

ROMarr listens on port 6868. Before you start, decide where its settings, downloads and ROMs will live. ROMs and downloads are usually far larger than the app.

Pick a method

Method Best for How
Docker Compose Most servers, NAS hosts, Docker Desktop See below
Unraid Unraid servers Official Community Applications listing (ghcr.io/blizzhacker/romarr)
Windows app Windows 10/11 x64 Download the Windows ZIP from Releases, extract it, run ROMarr.exe
macOS, Linux, SteamOS Desktops, laptops, Steam Deck ./scripts/start-desktop.sh from a checkout
Android Android 7+ phones, tablets, handhelds APK from Releases, or the Google Play beta
Proxmox LXC Proxmox hosts LXC installer
Home Assistant Home Assistant OS Add-on
From source Development, existing Python hosts Source install

Docker Compose quick start

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

Save as compose.yaml:

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/PGID to the owner of your ROM and download folders (id -u, id -g), then:

docker compose up -d

Open http://YOUR-SERVER:6868, set a password, and follow Settings → Setup Guide.

If you already use RomM, mount its real ROM folder instead of ./roms.

The rule that catches everyone

Your download client and ROMarr must see completed downloads at the same path. If the client says /downloads/game.zip, ROMarr must be able to open /downloads/game.zip too. Inside a container, localhost means the container itself, not your server. See paths that need to agree.

After installing

  • Settings you save in the web UI win over environment variables after the first run.
  • Your API key is under Settings → General. Use it for apps, scripts and AI Agents.
  • Back up the config folder. It holds your settings and history.

Full guide: INSTALL.md.

Clone this wiki locally