Downloading

Automatic Search

Comicarr runs two search loops continuously in the background:

Enable RSS checking with ENABLE_RSS in General settings. The full search runs regardless of this setting.

Search Provider Order and Tiers

Providers are queried in the order defined by PROVIDER_ORDER. When a result is found, Comicarr uses a tiered approach:

SEARCH_TIER_CUTOFF (default: 14 days) sets the window. If an issue was released within this many days, Comicarr uses only top-tier providers. After the cutoff, it expands to all configured providers.

This prevents slower or less reliable providers from being queried for brand-new releases, where top providers are most likely to have results.

Manual and Force Search

Beyond automatic searches, you can trigger searches manually:

• Manual Search: from the series or issue detail page, searches all providers for that specific issue.
• Force Search: bypasses quality filters and grabs the first matching result. Use this when the automatic search is not finding a match due to strict quality settings.

Interactive release search

When you want to see why a release was or was not accepted before anything is grabbed, use the interactive search. Start it on any wanted issue from the Releases page, or (since v0.32.0) directly from the issue's row on the series page, and from annual and story-arc rows. Comicarr opens a review sheet that fills in live as providers answer.

Since v0.34.0 a series page also has Review missing, an interactive search over the series' eligible missing issues as a whole. Results include pack releases, each release shows which missing issues it would satisfy, and a single grab can cover more than one issue. Per-issue interactive search works the same as before.

Each candidate carries a verdict:

Every verdict lists its reasons in plain language alongside the machine-readable reason code, so a rejection can be traced to the setting that caused it. The sheet also shows collection progress (which provider is being queried, how many are done) and names any provider that failed, so you can tell an empty result set apart from a broken indexer.

When one release turns up in the searches for several missing issues at once, the accepted verdict wins (since v0.34.2). Before that fix, whichever verdict arrived first could stick, which hid grabbable packs behind a "Not a match" label and could anchor a grab on an issue the pack does not contain.

Nothing is grabbed by browsing. A grab requires explicit confirmation and is revalidated at the moment you confirm it, so a candidate that went stale returns a conflict instead of being handed off. Grabs are idempotent, so a double click cannot snatch twice. Sessions are scoped to your browser session and expire.

Since v0.34.0 the grab's revalidation and download-client handoff run off the server's request loop, so the rest of the UI stays responsive while a grab is processing. Confirming a grab while another is still processing answers immediately with "Another release grab is already being processed".

Stopping in-flight work

Since v0.32.0 you can stop an in-flight search or an open download/post-processing item from Activity. The status bar's "N in flight" count opens Activity filtered to exactly those items, and each has a Stop action that moves it to cancelled instead of leaving you to wait for it to finish or fail.

Per-series search options

Two flags on each series detail page, under Search options, decide what the matcher will accept. Both default to off, and both are per-series:

Pack matching requires torrent search to be enabled (ENABLE_TORRENT_SEARCH). Since v0.34.0 pack releases are matched from any indexer. A result like Solo Leveling v01-14 or Invincible #001-144 is recognised as a multi-volume or multi-issue pack instead of being rejected for having no single issue number. Comicarr checks the pack against what the series is missing, and one grab marks every issue it covers as Snatched, so during "Search all missing" the queued searches for those issues stop instead of hunting for each one individually. A volume pack covers every chapter belonging to its volumes and only ever matches volume-tracked series, so v01-14 can never claim issues 1-14 of an issue-tracked comic.

The bare-title pack pass

A pack title usually carries no single issue number, so a query built around "Solo Leveling 001" will never return Solo Leveling v01-14. Since v0.36.0, a series with Allow packs on gets one extra query pass after the numbered ones, sending just the series title. That pass goes only to Torznab (torrent) indexers, where pack releases actually live, and only pack-shaped titles from it are evaluated, so a large indexer listing does not slow the search down. Two cases skip it: RSS mode, which reads a cached feed the numbered queries already covered, and TPB/HC/GN book types, which have always run a bare-title query of their own.

v0.36.0 also taught the pack detector two more release shapes:

The numberless shape is restricted to manga on purpose. A title like that carries no issue range at all, so a false positive claims the whole series in one go. On manga it is the normal way a complete-series release gets named; on a print comic a bracketed year span usually just states when the series ran, which would make that claim wrong. Grabbing one marks all the covered issues as Snatched, so "Search all missing" and Review missing stop hunting for them individually.

Download Client Handoff

When Comicarr finds a matching release, it sends it to your configured download client:

Usenet clients: SABnzbd, NZBGet, or Blackhole (write .nzb files to a directory).

Torrent clients: rTorrent, uTorrent, Transmission, Deluge, qBittorrent, or direct download (DDL).

Configure the active client under NZB_DOWNLOADER and TORRENT_DOWNLOADER in the Client section.

Comicarr monitors the download client every DOWNLOAD_SCAN_INTERVAL minutes (default: 5) to detect completed downloads.

Snatches and post-processing advances are recorded in a durable pipeline journal. After a crash or restart, open work is re-driven automatically. See Download Pipeline & Recovery.

Post-Processing Pipeline

Additional post-processing options:

• POST_PROCESSING_SCRIPT runs a custom script after processing.
• ENABLE_EXTRA_SCRIPTS and EXTRA_SCRIPTS run additional scripts.
• ENABLE_SNATCH_SCRIPT and SNATCH_SCRIPT run a script at snatch time, before the download completes.

Restart durability

Each release advances through journal stages (snatched → downloaded → post_processing → moved → post_processed, or failed). Startup recovery classifies client state (still / complete / gone / unknown) and either re-queues work or marks a download gone. Details: Pipeline & Recovery.

Failed Download Handling

When a download fails, Comicarr can automatically retry with a different release.

When enabled, failed NZBs/torrents are detected, the release is blocklisted, and a new search is triggered.

Blocklist

Failed releases are blocklisted to prevent re-downloading the same bad file.

BLOCKLIST_TIMER (default: 3600 minutes, or 60 hours) sets how long a release stays on the blocklist before it becomes eligible again.

Search Delay

SEARCH_DELAY (default: 1 second) pauses between individual search requests so providers are not hammered. Increase it if your search providers rate-limit you.

Usenet Retention

USENET_RETENTION (default: 3500 days) limits results to your provider's retention window. Set it to match what your usenet provider actually retains.