Skip to main content

Library Import

Questarr can import completed downloads into your library and discover games already on disk. Configure download imports in Settings → Import; its four sub-tabs form a two-by-two grid on phones. Manage existing directories in Library → Library Import.

Configure download imports

Enable Post-Processing, choose a Library Root, and save your changes. Questarr must be able to read the download source and write to the library root. In Docker, mount both locations and use their paths inside the container.

Naming pattern

The Naming Pattern controls the name of each imported game inside its platform folder: <Library Root>/<Platform>/<name>. Directory releases get a folder with that name. Single-file releases get a file with that name plus the original extension. The platform folder itself is not part of the pattern. See Platform Naming and Rename Patterns for the complete platform key and folder list, all rename-pattern tokens, and examples. Token names are case-insensitive. For example, {Title} ({Year}) [{Group}] renders The Example Quest (2021) [GROUP]. Questarr cleans up the rendered name before using it:
  • Empty tokens are dropped together with brackets that only held empty tokens and orphan separators. {Title} ({Year}) renders Doom when the year is unknown.
  • Characters that file systems refuse (< > : " / \ | ? * and control characters) become _.
  • Names matching Windows reserved device names, such as CON or LPT1, get a _ prefix.
  • Names are capped at 200 bytes (UTF-8) and trailing dots and spaces are removed.
  • If nothing usable remains, Questarr falls back to the sanitized game title.
The default pattern stays {Title} ({Region}). Because {Region} is always empty, it renders as the plain title, and existing configurations keep their current pattern. In Settings → Import, the pattern editor offers:
  • Token chips that insert a token at the cursor.
  • Presets: {Title}, {Title} ({Year}), {Title} ({Year}) [{Group}], and {TitleThe}.
  • Inline validation. Unknown tokens, slashes, .., control characters, empty patterns, and unbalanced braces show an error and disable Save.
  • Live preview of a sample game, followed by the full destination paths for up to five games from your library and a sample release.
The pattern applies to new imports only. Questarr does not rename folders or files that were already imported.

Path mappings and security

If your downloader reports paths Questarr cannot access, open the Path Mappings subtab. Map the downloader’s remote path to the corresponding local path visible to Questarr. For example, map /downloads to /data/downloads when those paths refer to the same mounted files. The Security subtab optionally enables VirusTotal hash checks and/or ClamAV scanning before unpacking or transferring files. Configure each provider and use its connection test. A detection quarantines the download and produces a Security Alert instead of importing it. See SECRETS.md for archive limits and credential handling.

RomM integration

RomM scans <library>/roms/<platform>/... and recognizes a platform from the folder name. The RomM card in Settings → Import lets Questarr import into that layout and talk to RomM. Questarr does not ship RomM: you host your own instance. Use Test connection to check the URL and token without saving them, and Sync now to run the ownership sync on demand. The saved token is only ever sent to the saved URL, so changing the URL means entering the token again. Questarr warns when the URL uses http://, because the token then travels unencrypted. The token is encrypted at rest and never returned by the API.

How completed downloads are imported

Questarr checks completed downloads, translates their paths, determines the platform and destination, and imports the files using the configured transfer mode. Enabled archive extraction runs as part of this process. Successful imports link files to the game and mark it Owned; Playing, Shelved, and Completed statuses are preserved. Wii U releases and games identified by IGDB as Wii U use the Wii U platform folder when Questarr selects the import destination. Archive extraction stages the contents before merging them into the destination. When importing an update into an existing game folder, files supplied by the archive replace same-named files; unrelated installed files and saves remain. File/directory conflicts and symlinked destination directories require correction before retrying. If an error reports an incomplete rollback or a retained .questarr-extract-*.bak directory, inspect its original files and the reported paths before retrying or deleting it. If a path is missing, a platform cannot be resolved, extraction needs a password, or an import fails, the download is held for review instead of being silently marked imported.

Manual review in the Library

The Pending Manual Imports panel in the Library lists downloads requiring attention. Expand it when several items are collapsed, then use the action shown:
  • Review opens the import dialog. Check the source, destination, contents, transfer mode, and unpack option, then choose Confirm Import. The dialog also offers Symlink as a manual transfer mode.
  • Enter Password supplies the archive password before retrying extraction.
  • Link Game attaches a download whose original game record is missing.
  • Skip removes an item from the pending queue. Quarantined items offer Dismiss and cannot be imported from this panel.
Correct inaccessible paths or mounts before retrying a failed import. Reviewing a downloaded file is separate from confirming an IGDB match for an existing folder below.

Import history

Open Activity → Import History to inspect Steam wishlist, file-import, and Scan Unlinked tasks. The list shows the trigger, status, start time, duration, and added/skipped/failed counts. Select a task to see individual game results, fuzzy matches, and error messages. Running tasks update as they progress. Root-folder scan progress and unmatched candidates are shown on Library Import; they are temporary scan state rather than a persistent Import History record.

Discover games already on disk

Open Library → Library Import to discover games already on disk outside the Library Root used for download imports. Add an existing readable directory with Add Folder, optionally give it a label, and Questarr scans it automatically. Use paths visible to the Questarr process; in Docker, mount the directory and enter its container path, not the host path. Games with a confident IGDB match are added as Owned and linked to their existing files. Discovery does not move or rename those files. Allow Delete is off by default: removing a game with its files skips files discovered under that root unless you explicitly enable this permission. Removing a root-folder configuration does not delete the directory itself.

Scans and review

  • Adding or enabling a root folder, or changing an enabled folder’s path, starts a scan. Enabling post-processing in Settings → Import also scans enabled roots.
  • Scan runs one enabled folder; Scan All runs all enabled folders. Changes to folder settings during an active scan queue a follow-up rescan.
  • Progress shows queued/running/completed/failed status and matched, review, and error counts. Library and Discover refresh when matches are saved, including matches saved before a scan fails.
  • A folder already linked to a game, by an earlier scan or a manual match, is not looked up on IGDB again and never returns to Needs Review. A rescan still attaches any new files found in it.
  • Nintendo Switch dumps are recognised by the title id in the file or folder name (for example Hades [0100535012974000][v0].nsp). Flat files match like folders do, and an update or DLC joins its base game.
  • Folder names can help the match. A release year in brackets, such as Celeste (2018) or Portal [2007], is left out of the IGDB query and used to pick between games of the same name. An id tag is an exact match: {igdb-1234} names the IGDB game, {steam-620} a Steam app that Questarr resolves to its IGDB game (round or square brackets work too). An id IGDB does not know falls back to the title search.
  • The scan asks IGDB for ten candidates per folder, since a short name such as “Portal” is crowded with sequels and mods. Needs Review lists up to ten, likeliest first, each with its cover and release year.
  • A folder that stays in Needs Review is explained in the server log (search Library scan: folder left in Needs Review): the query sent to IGDB, how many candidates came back, and the best one with its score against the 0.85 threshold.
  • Under Needs Review, choose a suggested IGDB game or enter a different name in Not listed? Search IGDB by name. Search alone does not import the game; clicking a candidate confirms it and adds it to your library.
  • Ignore removes a folder from Needs Review for good, for example a Proton build next to your games. Later scans skip it before listing its files, unless it is already linked to a game. Ignored folders are listed under Ignored Folders, where Restore brings one back and queues a rescan of its root folder. Ignore and candidate matching are disabled while the other is in progress.
If a folder is inaccessible, check the mount and the service user’s permissions, then use its health-recheck button. If IGDB search fails, the folder stays in review so you can retry. Scan progress and unmatched candidates are in-memory state; run another scan after a server restart to recreate them. See API.md for scan and review endpoints and SECRETS.md for filesystem and extraction limits.

Download tracking and recovery

An unreachable download client leaves tracked downloads active. Torrent errors remain tracked for a 30-minute grace period so they can recover; Usenet failures are treated as final. Auto-search skips a release that previously failed for the same game; you can choose another release manually. After a restart, an interrupted import appears in Pending Manual Imports. A download removed by its client near completion also goes there when post-processing is enabled: review the downloaded files and confirm their source path. With post-processing off, a job last seen near completion is considered completed. These decisions use the last state observed during the current server run; they do not prove that a vanished job finished successfully.

Incomplete scans, disc images and extras

If ClamAV is unavailable, refuses a file, cannot enumerate the full download, or reaches its file/time budget, the download waits in Pending Manual Imports without being moved to quarantine. Review the stated reason before confirming an import anyway. If confirmation first discovers an incomplete scan, it stops and asks you to confirm again after reading the reason. Actual detections still block and quarantine the download. For large game files, review clamd.conf limits StreamMaxLength, MaxFileSize and MaxScanSize. Scans allow up to 10,000 files and a 30-minute total budget. VirusTotal lookup outages retain their existing behavior. Auto-Unpack keeps .iso and split .iso.NNN disc images intact. An explicit manual unpack request can extract them. Sort Extras categorizes release-level items and may skip one outer release wrapper; it preserves internal game directories instead of treating names such as Data/Patch as separate updates. Explicit update/extra names take precedence over edition words, and category folders inside a release wrapper are sorted into their matching categories.