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
Enabled	on	toggle	Master switch for automatic searches.
Scan interval (h)	6	1–168	Hours between scans. Lower = fresher search results, higher provider load.
Search on startup	on	toggle	Run a scan 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)	24	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 (%)	25	0–80	Percentage of each scan reserved for items aged > 7 days. Stops new releases starving older requests.
Priority weighting	on	toggle	Older / higher-profile items search first within a cycle.
Search order	priority	priority / fifo	Within a scan cycle, order to process items.

Tip

For libraries below 5,000 items, every 6 hours is overkill — 12 or 24 is fine. For active *arr setups (new episodes nightly), every 2-3 hours catches new releases faster than the default.

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)	4	1–168	How often Sublarr re-walks Standalone folders. *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)	24	1–168	How often Sublarr scans for upgrade candidates.
Upgrade min score delta	0.5	0.1–10	Replace only if the new candidate beats the current by at least this.
Upgrade max attempts	3	1–10	Per-item cap on upgrade attempts before giving up.

The replaced subtitle goes to Trash for the configured retention.

Caution

Lowering Upgrade min score delta below 0.3 causes Sublarr to repeatedly swap subtitles that score nearly equally — wasting bandwidth and confusing media servers. Stick at 0.5 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	4	1–32	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.