Settings — Search & Scan

This page configures the heartbeat of Sublarr’s automation: how often the wanted scanner runs, how many providers it asks in parallel, and whether existing subtitles get upgraded when a better one appears. The defaults are sane for most installs — only tweak when you’re hitting provider rate limits or running on constrained hardware.

Wanted scanner

The scanner walks the library, identifies items missing target-language subtitles, and queues searches.

Setting	Default	Values	Effect
Scan interval (h)	0	0–168	Hours between library scans. 0 disables periodic scans; webhooks and manual scans still work.
Scan on startup	off	toggle	Run a library scan immediately when Sublarr boots.
Wanted search interval (h)	24	0–168	Hours between provider-search runs for queued wanted items. 0 disables the periodic search job.
Search on startup	on	toggle	Run a wanted search immediately when Sublarr boots.
Backoff on 429	on	toggle	Slow down when a provider rate-limits. Strongly recommended on.
Backoff base (h)	1	0.25–24	Initial backoff delay after a rate-limit.
Backoff cap (h)	168	1–168	Maximum backoff. Provider unsticks fully after this.
Adaptive backoff	on	toggle	Per-provider backoff state. Disable for predictable per-cycle behaviour.
Backlog reserve (%)	50	0–80	Percentage of each scan reserved for older backlog items. Stops new releases starving older requests.
Priority weighting	on	toggle	Older / higher-profile items search first within a cycle.
Search order	fair	fair / newest_first / weighted	Within a scan cycle, order to process items.

Tip

For active Sonarr/Radarr setups, keep periodic scans disabled and rely on webhooks plus the 24-hour wanted search sweep. Use a scan interval only when your stack cannot send webhooks reliably.

Library scan

Independent of the wanted scanner — the library scan is what discovers files in the first place (Standalone mode) or syncs with Sonarr/Radarr (*arr mode).

Setting	Default	Values	Effect
Standalone scan interval (h)	6	0–168	How often Sublarr re-walks Standalone folders. 0 disables periodic Standalone scans. *arr mode uses webhooks instead.
Skip extras	on	toggle	Skip files matching the configured “extras” patterns (trailers, behind-the-scenes).
Min file size (MB)	100	0–10000	Reject files below this size as not real content.
Ignore patterns	*.tmp,*.partial,*sample*	comma-separated globs	Filenames that match any pattern are skipped.
Ignore languages	empty	comma-separated codes	Existing sidecars in these languages are ignored when computing “missing language”.
Yield (ms)	0	0–500	Sleep between file probes. Raise on slow storage to avoid IO saturation.
Min metadata workers	4	1–32	Parallel metadata lookups. Raise on fast storage + good network.

Upgrades

When Upgrade enabled is on (per-profile and globally), Sublarr replaces existing subtitles with better-scoring ones found in subsequent searches.

Setting	Default	Values	Effect
Upgrade enabled	on	toggle	Global master. Per-profile setting can disable for specific series.
Upgrade scan interval (h)	0	0–168	How often Sublarr scans for upgrade candidates. 0 disables scheduled upgrades; manual upgrade scans still work.
Upgrade min score delta	50	score points	Replace only if the new candidate beats the current by at least this.
Upgrade window (days)	7	days	Only subtitles inside this age window are considered for upgrades.
upgrade_protect_user_modified	on	toggle	New in 1.10.0. Never auto-replace a subtitle you edited by hand.

The replaced subtitle goes to Trash for the configured retention.

Protecting your own edits. Once you save a change in the subtitle editor, Sublarr marks that file as hand-edited. With upgrade_protect_user_modified on — the default — the upgrade pass skips it, so an hour spent fixing timings is not undone by a marginally better-scoring download. Turn it off only if you want automation to win unconditionally.

Caution

Lowering Upgrade min score delta too far causes Sublarr to repeatedly swap subtitles that score nearly equally — wasting bandwidth and confusing media servers. Keep the default unless you have a specific reason.

Concurrent searches

Sublarr caps how many provider calls run in parallel. Lower caps protect upstream providers; higher caps drain a wanted backlog faster on capable hardware.

Setting	Default	Values	Effect
Max concurrent provider searches	3	1–10	Per-Sublarr-instance global cap.
Per-provider concurrency	2	1–8	Cap per provider. Some providers throttle aggressively per-IP.
Provider delay (ms)	0	0–5000	Sleep between consecutive calls to the same provider. Use when a provider rejects rapid sequential calls.

Trigger a scan manually

Three buttons at the top of the page:

Button	Effect
Scan library now	Runs library scan once.
Search wanted now	Runs wanted scanner once.
Upgrade scan now	Runs upgrade scan once.

Manual triggers respect the same concurrency caps and rate limits as the scheduled equivalents.

Where the underlying scheduler lives

The actual jobs that run on these intervals are owned by APScheduler under Settings → System → Scheduler. This page is a high-level surface for the most-tuned settings; the Scheduler page exposes raw cron triggers, history, and per-job pause/resume.