Questarr

A video game management application inspired by the -Arr apps (Sonarr, Radarr, Prowlarr...) and GamezServer. Track and organize your video game collection with automated discovery and download management.

⭐ Star us on GitHub — your support motivates us a lot! 🙏😊

Table of Contents

• Questarr
  • Table of Contents
  • List of features
  • Installation
  • Screenshots
  • Release classification
  • Tech Stack
  • Configuration
  • Roadmap
  • Troubleshooting
  • Project Security & Documentation
  • Contributing
  • License
  • Acknowledgments

List of features

Feature	Description
Backlog management	Track game status, ratings, notes, and your play journal. Use Backlog roulette to pick a game from Library or Playing.
Game Discovery	Browse IGDB, RSS, and xREL.to, manage ratings and visibility from game details, sync your Steam wishlist, or discover games on disk with Library Import.
Search & Filter	Find games by genre, platform, and keyword, with automatic search until a release is found, plus release blacklisting and preferred release groups/platforms. Settings → Appearance → Platforms scopes the app to your chosen platforms, with optional filters to hide shelved/owned games and age-restricted or erotic content.
Download Management	Automate downloads and library imports, with archive updates that preserve unrelated installed files, manual review, optional security scanning, and experimental AI matching.
Release Classification	A local machine-learning model tells the game from the patch, DLC, crack-only or demo release before an automatic download. The local model ships with Questarr and runs offline, no key needed. See Release classification.
Real-time Notifications	Choose in-app and Apprise alerts, including update controls for Shelved and Completed games.
Rich Game Metadata	Details enriched with IGDB, Steam, PCGamingWiki, and NexusMods, including trending mods where available.
Statistics	Visualize collection statistics with Discord sharing support. 🚧
Security Focused	General security hardening, SSL support, and — see for the full process.

Supported Indexers/Downloaders

• Sync indexers from Prowlarr.
• G4u.to: the site offers an API to VIP members, which can be used in Questarr.

Indexers	Downloaders
Torznab protocol (Torrent)	- qBittorent- Transmission- rTorrent- Deluge- Synology Download Station
Newznab protocol (Usenet)	- Sabnzbd- Nzbget
G4U.to	Same as Newznab

Installation

Docker is the easiest way to deploy Questarr with all dependencies included. Since 1.5.0, native Windows installation is also supported via the Windows installer. Questarr uses SQLite by default, with optional PostgreSQL support. Persist the data volume to retain the SQLite database, configuration, and encryption keys.

Supported architectures: released Docker images are published for linux/amd64 and linux/arm64, so Questarr runs on a Raspberry Pi 4/5 with a 64-bit OS, other 64-bit ARM SBCs, and ARM-based NAS boxes as well as on x86 hardware. Docker selects the right architecture automatically — the commands below are identical on every platform. (32-bit ARM, e.g. armv7/a 32-bit OS on Raspberry Pi 3 and earlier, is not supported. The Home Assistant add-on is amd64-only.)

Option 1: One-liner (Simplest but minimal)

docker run -d -p 5000:5000 -v ./data:/app/data --name questarr ghcr.io/doezer/questarr:latest

Option 2: Docker Compose (more detailed)

1. Use the docker-compose.yml file from the repo or create a minimal one:

   services:
     app:
       image: ghcr.io/doezer/questarr:latest
       ports:
         - "5000:5000"
       volumes:
         - ./data:/app/data
       environment:
         - SQLITE_DB_PATH=/app/data/sqlite.db
       restart: unless-stopped
   

2. Start the application:

   docker compose up -d
   

3. Access the application: Open your browser to http://localhost:5000

4. Optional — use Postgres instead of SQLite:

   Questarr uses SQLite by default and needs no database configuration. If you would rather run it against Postgres, use the bundled compose file:

   POSTGRES_PASSWORD=$(openssl rand -hex 32) docker compose -f docker-compose.postgres.yml up -d
   

   Keep whatever password you pick — the same value must be supplied on every restart, and it must be safe to embed in a connection URL (a hex string from openssl rand -hex 32 always is).

   Switching an existing SQLite install to Postgres does not move your data — run scripts/sqlite-to-pg.ts to bring your library across. See docs/DATABASE.md.

Windows (installer)

Prefer running Questarr as a native Windows service instead of Docker? Download QuestarrSetup-<version>-windows-x64.exe from the GitHub releases, choosing a 1.5.0 or later release with the installer attached, and run it. The installer bundles Node.js, installs Questarr as a Windows service (Questarr.Service.exe), and starts it automatically — open http://localhost:5000 once it finishes.

Proxmox VE (LXC)

Run this on your Proxmox VE host, as root, to create an LXC container with Questarr installed and running as a systemd service:

bash -c "$(curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' https://raw.githubusercontent.com/Doezer/Questarr/main/scripts/proxmox/questarr-lxc.sh)"

The script picks the next free container ID, downloads a Debian template if needed, creates an unprivileged container, builds Questarr from source, and prints the URL to open. Every prompt has a default, so you can accept them all and be done in a few minutes.

Update later with pct exec <ctid> -- update.

See docs/PROXMOX.md for non-interactive installs, sizing guidance, configuration, and troubleshooting.

UNRAID

Questarr is available in the Unraid Apps tab via Community Applications:

1. Open the Apps tab and search for Questarr, then click Install.
2. Set your Data Path (default /mnt/user/appdata/questarr), PUID/PGID, and ports (default 5000 HTTP, 9898 HTTPS if using it).
3. Optionally set Library Path to the same root your download client(s) write into (e.g. /mnt/user/data) if you want Questarr to move completed downloads into your game library. This host path is mounted at /data inside the container, so add a mapping under Settings → Path Mappings with Local Path set to /data and Remote Path set to the exact path your download client reports for that root. Leave Library Path blank if you manage imports manually.
4. Apply, then open http://<unraid-host>:5000 to access the UI.

CasaOS

1. Open the App Store and click Custom Install.
2. Click the import icon (top right) and paste this URL: https://raw.githubusercontent.com/Doezer/Questarr/main/casaos/docker-compose.yml
3. Review the mounts — by default /DATA/AppData/questarr holds Questarr's data and /DATA/Downloads is mounted at /data so Questarr can import finished downloads. If you keep that second mount, add a matching entry under Settings → Path Mappings.
4. Click Install, then open Questarr from the CasaOS dashboard (port 5000).

Umbrel

1. In umbrelOS, open the App Store.
2. Click the ⋮ menu (top right) → Community App Stores.
3. Add this repository URL: https://github.com/Doezer/Questarr
4. Open the Doezer store and install Questarr (app ID doezer-questarr), then open it from your dashboard (http://umbrel.local:5000).

Cosmos Cloud

1. Open Market Place → Custom Install (or Servapps → Add).
2. Paste this URL: https://raw.githubusercontent.com/Doezer/Questarr/main/cosmos/questarr.cosmos-compose.json
3. Fill in the install form: Data folder, optional Library folder (the root your download client writes into, mounted at /data), and PUID/PGID.
4. Install. Cosmos creates the route questarr.<your-server-hostname> and handles HTTPS for you.

Kubernetes (Helm)

A Helm chart lives in charts/questarr. It is not published to a Helm repository yet, so install it from a clone:

git clone https://github.com/Doezer/Questarr.git
cd Questarr
helm install questarr charts/questarr --namespace questarr --create-namespace

Then port-forward (or enable the Ingress) and open the UI:

kubectl port-forward -n questarr svc/questarr 5000:5000

Questarr keeps its state in a single SQLite database on a ReadWriteOnce volume, so the chart never runs more than one replica. See charts/questarr/README.md for the full option reference — persistence, media mounts, secrets, Ingress and subdirectory deployments.

Home Assistant Add-on

You can install Questarr as a Home Assistant add-on from this repository:

1. In Home Assistant, open Settings → Add-ons → Add-on Store.
2. Click the menu (⋮) and choose Repositories.
3. Add this repository URL: https://github.com/Doezer/Questarr
4. Install the Questarr add-on and start it.
5. Open http://<home-assistant-host>:5000 to access the UI.

All platform definitions live in the repository and share the same mounts and ports — see docs/HOME_SERVER_APPS.md for details.

Screenshots

Library

Your central hub for recent activity, collection overview and downloading available games. Manage your owned and wanted games.

Wishlist & Release calendar

Manage your wanted games and when they release.

Discover Games

Browse and find new games to add to your collection. Download from a game’s details to add it as Wanted and send a release to your downloader.

RSS & xRel.to feeds

Discover releases through RSS feeds and xREL.to, with IGDB matching.

Downloads Queue

Monitor your downloaders' active downloads and history.

Statistics

Check out your library statistics.

Settings

Configure indexers, downloaders, and application preferences.

Release classification

Indexers return a lot of look-alikes: the game, a day-one patch, a DLC, a crack-only folder, a demo, a soundtrack. A fixed list of keywords cannot tell them apart reliably, because release names are inconsistent and the same words mean different things in different titles. Questarr classifies each release with a small machine-learning model and holds back the ones that are probably not the full game.

What you get

• Fewer wrong grabs. Before the automatic search sends a release to your download client, patches, DLC, expansions, crack-only releases, demos, soundtracks and other extras are held for your review instead of being downloaded.
• Works offline. The second layer is a local model (tf-idf with logistic regression) that runs on your machine. No account, no API key, and release names are not sent anywhere.
• Learns from names, not only keywords. It weighs the whole release name, so it handles spellings and group conventions that a hand-written rule list misses.
• Optional cloud model. In hybrid mode, the TypeSafe cloud model only receives the releases the rules and the local model could not settle (or all unsettled releases, if the local model cannot be loaded). In cloud mode it handles them without the local model. Use local mode to keep release names on your server.
• Gets better with your input. Optional active learning keeps the releases the classifier was unsure about so you can verify them in Settings and export the confirmed labels as CSV. Nothing is retrained automatically, a cloud suggestion is never stored as a verified label, and the labels and matches you provide stay on your server: they are never sent anywhere, not even to the cloud model.

How it works

1. Fast rules catch the obvious cases.
2. The local model decides when it is confident enough (threshold 70% by default).
3. Only what is left can go to the cloud model, if you enabled it.

The local model is bundled with Questarr (including the Docker image), so it works out of the box. To use your own, place a release-classifier.json in <database folder>/models/ or point CLASSIFIER_MODEL_PATH at it; it takes priority over the bundled one (see The local model). If no model can be loaded, only the rules run locally, and hybrid sends every release the rules cannot settle to the cloud model, if one is configured.

Choose the mode in Settings → Release classification: hybrid (default), local (never leaves your machine) or cloud. The same card controls the confidence threshold, holding unclassified releases, and active learning. An environment variable, when set, wins over the saved setting and locks the field. The same pipeline types the manual search results and decides the automatic-download hold, so a release gets one type everywhere.

Details, environment variables and the dataset are in docs/RELEASE_CLASSIFICATION.md.

Tech Stack

• APIs: IGDB (game metadata), Torznab/Newznab (indexer search), PCGamingWiki, NexusMods, xREL.to
• AIs usage:
  • Claude and Github Copilot are used for AI-Assisted coding, internal code reviews, PR cleanup. Eventually automated coding and troubleshooting for small tasks and bug reports.
  • Gemini & Codex are used for automated code reviews, and brainstorming from time to time (as well as Perplexity for this usage).
  • Google Jules is used for light periodical refactoring.

Configuration

1. First-time setup:

• Create your admin account
• Configure the IGDB credentials

Once logged-in:

• Configure indexers
• Add downloaders
• Add games!

See Configuration on the Wiki for more detailed info.

IGDB provides game metadata (covers, descriptions, ratings, release dates, etc.).

1. Go to Twitch Developer Console
2. Log in with your Twitch account (create one if needed)
3. Click "Register Your Application"
4. Fill in:
   • Name: Questarr (or any name)
   • OAuth Redirect URLs: http://localhost (not used, but required)
   • Category: Application Integration
5. Click "Create"
6. Copy your Client ID and Client Secret
7. Add them to your .env file

If you are upgrading from an older version that used PostgreSQL, you need to migrate your data.

The migration tooling was removed in v1.5.0 and is now run from the archived v1.4.2 release. Follow docs/MIGRATION.md, which inlines the pinned compose file and links the sources by tag permalink.

This is only for pre-v1.1 PostgreSQL installations. Running Questarr on PostgreSQL as an opt-in backend is a separate feature — see docs/DATABASE.md.

See docs/MIGRATION.md for more details.

Docker compose

This is mainly for users who want the latest commit (e.g when trying out fixes for an issue) or contributing users.

1. Clone the repository:

git clone https://github.com/Doezer/Questarr.git
cd Questarr

1. Configure the application: Edit docker-compose.yml directly if you need to setup a specific environment.

2. Build and start the containers:

docker-compose up -d

1. Access the application: Open your browser to http://localhost:5000

Update to latest version for Docker

Your database content will be kept.

git pull
docker-compose down
docker-compose build --no-cache
docker-compose up -d

Reverse proxy / subdirectory deployment

Want to serve Questarr from a path like https://xxx.domain.com/Questarr instead of its own subdomain? Set QUESTARR_BASE_PATH=/Questarr on the container (or in .env for npm installs) and point your reverse proxy at it — no rebuild required. See docs/REVERSE_PROXY.md for full setup instructions (nginx, Traefik, Caddy).

Behind any reverse proxy, also set TRUST_PROXY=1 so rate limits see real client IPs (see the same doc).

Roadmap

Based on the Product Requirements Document, here is the release status and remaining work, in priority order:

• ✅ P0 — Post-Processing Pipeline : Move/copy completed downloads to a destination path, extract archives — closing the "set it and forget it" loop.
• P1 — Smart Game Backlog: Installed-version tracking and update filtering are available; configurable automatic upgrades remain a priority.
• P2 — Direct Download Support: Add debrid services (Real-Debrid and similar) as a downloader option, no seeding required.
• P3 — External Library Sync: Import owned games from Steam/GOG libraries and local filesystem scans, not just wishlists.
• P4 — Integrations with External Tools: ✅ Playnite extension shipped (library sync, request-to-download); RomM, Gameyfin, and a generic webhook for anything not explicitly supported are still planned.
• ✅ P5 — Indexer Page Links: A "View on indexer" link on search results and downloads.
• ✅ P6 — PostgreSQL Support: PostgreSQL is available as an optional backend, with SQLite remaining the zero-config default.

Ongoing: mobile responsiveness, search UX, performance, and security improvements.

See the full PRD for problem statements, detailed scope, and non-goals.

Troubleshooting

See Troubleshooting on the Wiki

If you run into an issue, go to the Logs page and click Send Logs before reporting it — it makes diagnosing the problem much easier.

Getting Help

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Discord: Join our Server

Project Security & Documentation

• Start with docs/GITHUB_DOCUMENTATION.md for the canonical documentation map.

Star History

Contributing

• See .github/CONTRIBUTING.md for guidelines on how to contribute to this project.
• See MAINTAINERS.md for the current list of project members with access to sensitive resources.

Contributors

Made with contrib.rocks.

Legal Disclaimer

Questarr is a self-hosted game manager designed solely for organizing, tracking, and automating game libraries using user-provided data and metadata APIs (such as IGDB). Questarr does not host, distribute, or provide any copyrighted game content, ROMs, or download links. It is a technology-neutral tool: any indexers, download clients, or sources you configure are chosen and operated entirely by you. You are solely responsible for ensuring that your use of Questarr, and any content you access or download through third-party services you configure, complies with all applicable laws and the terms of service of those third parties.

License

GPL-3.0-only - see COPYING for the full license text.

Acknowledgments

• Inspired by Sonarr and GamezServer
• Game metadata powered by IGDB API
• UI components from shadcn/ui
• Security scanning supported by Snyk through the Snyk Open Source program
• AI code reviews by CodeRabbit, free for open source
• This project is tested with BrowserStack