Downloading
How Comicarr searches for, downloads, and post-processes comic files automatically.
Automatic Search
Comicarr runs two search loops continuously in the background:
| Loop | Interval | Config Key | Purpose |
|---|---|---|---|
| RSS Check | Every 20 minutes | RSS_CHECKINTERVAL | Scans provider RSS feeds for new releases. |
| Full Search | Every 1440 minutes (24h) | SEARCH_INTERVAL | Runs a full query against all providers for all wanted issues. |
Enable RSS checking with ENABLE_RSS in General settings. The full search runs regardless of this setting.
Set NZB_STARTUP_SEARCH to True to trigger a full search immediately when Comicarr starts, rather than waiting for the first scheduled interval.
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) -- 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. Results are presented for you to choose from.
- 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.
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.
Post-Processing Pipeline
File operation
The completed file is moved or copied from the download directory to the library, controlled by FILE_OPTS (move or copy).
Rename
If RENAME_FILES is enabled, the file is renamed according to your FILE_FORMAT template.
Metadata tagging
If ENABLE_META is enabled, Comicarr writes ComicVine metadata into the file using ComicTagger. Supports both ComicRack (CR) and ComicBookLover (CBL) tag formats.
Additional post-processing options:
POST_PROCESSING_SCRIPT-- run a custom script after processing.ENABLE_EXTRA_SCRIPTS/EXTRA_SCRIPTS-- run additional scripts.ENABLE_SNATCH_SCRIPT/SNATCH_SCRIPT-- run a script at snatch time (before download completes).
Failed Download Handling
When a download fails, Comicarr can automatically retry with a different release.
| Setting | Default | Description |
|---|---|---|
FAILED_DOWNLOAD_HANDLING | False | Enable automatic failed download handling. |
FAILED_AUTO | False | Automatically search for a replacement when a failure is detected. |
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 / 60 hours) -- how long a release stays on the blocklist before it becomes eligible again.
If you are seeing repeated failed downloads for the same issue, check your provider health and quality settings before reducing the blocklist timer.
Search Delay
SEARCH_DELAY (default: 1 second) -- pause between individual search requests to avoid hammering providers. Increase this if you experience rate limiting from your search providers.
Usenet Retention
USENET_RETENTION (default: 3500 days) -- only consider results within your provider's retention window. Set this to match your usenet provider's actual retention.