Skip to content

Configuration File Reference

This comprehensive guide explains every setting in Torrentarr's config.toml configuration file.

Configuration File Location

Native Installation

~/config/config.toml           # Linux/macOS
%USERPROFILE%\config\config.toml  # Windows

Docker Installation

/config/config.toml  # Inside container

Mounted from your host at the path specified in your Docker compose/run command.

File Format

Torrentarr uses TOML (Tom's Obvious, Minimal Language) for configuration.

TOML basics:

# Comments start with #
key = "value"
number = 42
boolean = true
list = ["item1", "item2", "item3"]

[Section]
nested_key = "nested value"

[[ArrayOfTables]]
name = "first"

[[ArrayOfTables]]
name = "second"

Configuration Sections

Torrentarr's configuration is organized into several sections:

  1. Settings - Global Torrentarr settings
  2. WebUI - Web interface configuration
  3. qBit - qBittorrent connection
  4. Sonarr-* - Sonarr instance configuration
  5. Radarr-* - Radarr instance configuration
  6. Lidarr-* - Lidarr instance configuration

Settings Section

The [Settings] section contains global configuration that applies to all Torrentarr operations.

Complete Settings Example

[Settings]
# Internal config schema version - DO NOT MODIFY
ConfigVersion = "6.20.3"

# Logging
ConsoleLevel = "INFO"
Logging = true

# Timers
NoInternetSleepTimer = 15
LoopSleepTimer = 5
SearchLoopDelay = -1

# Special categories
FailedCategory = "failed"
RecheckCategory = "recheck"

# Torrent processing
Tagless = false
IgnoreTorrentsYoungerThan = 180

# Network
PingURLS = ["one.one.one.one", "dns.google.com"]

# FFprobe
FFprobeAutoUpdate = true

# Auto-updates
AutoUpdateEnabled = false
AutoUpdateCron = "0 3 * * 0"
AutoUpdateChannel = "latest"

# Process management
AutoRestartProcesses = true
MaxProcessRestarts = 5
ProcessRestartWindow = 300
ProcessRestartDelay = 5

ConfigVersion

ConfigVersion = "6.20.3"

Type: String Default: "6.20.2" Required: Yes (managed automatically)

Internal configuration schema version. DO NOT MODIFY this value manually. Torrentarr uses it to detect when config migrations are needed. Updated automatically when Torrentarr migrates an older config to the current format.

The numeric major of this field follows Torrentarr’s release policy: one major version ahead of qBitrr’s (e.g. while qBitrr is on 5.x, Torrentarr’s line is 6.x). It is not meant to equal qBitrr’s package version.

ConsoleLevel

ConsoleLevel = "INFO"

Type: String Default: "INFO" Options: CRITICAL, ERROR, WARNING, NOTICE, INFO, DEBUG, TRACE

Controls logging verbosity. Higher levels include all lower levels.

Level descriptions:

  • CRITICAL - Only fatal errors
  • ERROR - Errors that need attention
  • WARNING - Warnings and errors
  • NOTICE - Important notices, warnings, and errors
  • INFO - (Recommended) General information
  • DEBUG - Detailed debugging information
  • TRACE - Very verbose, traces all operations

Recommendation: Start with INFO. Switch to DEBUG when troubleshooting.

Logging

Logging = true

Type: Boolean Default: true

Enable or disable logging to files. When enabled, logs are written to:

  • Native: ~/logs/ or %USERPROFILE%\logs\
  • Docker: /config/logs/

Log files created:

  • Main.log - Torrentarr main process
  • WebUI.log - Web interface
  • Radarr-<name>.log - Per Radarr instance
  • Sonarr-<name>.log - Per Sonarr instance
  • Lidarr-<name>.log - Per Lidarr instance

Recommendation: Keep enabled for troubleshooting.

Client download paths and free-space monitors

Download roots and space protection are configured per torrent client, outside [Settings]:

[TorrentClient.local]
Type = "qbittorrent"
Host = "localhost"
Port = 8080
DownloadPath = "/downloads"
TorrentScanIntervalSeconds = 30
FreeSpace = [
  { Path = "/data/downloads", Enabled = true, Limit = "50G" },
  { Path = "/data/archive", Enabled = false, Limit = "100G" }
]

[[TorrentClient.local.Maintenance.PathMappings]]
ClientPath = "/downloads"
LocalPath = "/data/downloads"

The same fields work in legacy [qBit] and [qBit-name] sections. DownloadPath is the default root as seen by the client, used when creating missing categories. Existing category paths are preserved. Monitor Path values are absolute paths as seen by Torrentarr; mounts must already exist. Path mappings translate between these views without moving files.

New clients have no monitors. New monitor rows start disabled with a 10G limit. Limits accept nonnegative bytes or K/M/G/T suffixes (powers of 1024); use Enabled = false to disable a row. Duplicate paths are rejected, while temporarily unavailable paths may still be saved.

TorrentScanIntervalSeconds accepts only 5, 15, 30, 60, 90, or 120 seconds; new clients default to 30. Arr and qBit-only torrent processing, tracker sorting, failed/recheck handling, and routine protection inspections follow this per-client interval. Free space checks use the shortest interval among clients sharing each filesystem. Independent filesystems keep separate deadlines. Scans run immediately at startup; configuration changes and client reconnections can wake processing early. Each loop runs sequentially and skips missed ticks; slow operations and error backoff can delay scans. Fresh safety checks and manual actions may run between scans.

Exactly one host-owned FreeSpaceManager reads the client inventories and allocates space per shared filesystem. Clients and paths on the same storage share one budget and the largest enabled reserve. Remaining active unmanaged downloads consume that budget too. Managed downloads are evaluated globally oldest first by added date, reserving each torrent's remaining bytes once, and only downloads that do not fit are paused. User-paused torrents remain paused.

Unavailable enabled paths pause affected managed downloads and withhold resumes; healthy independent storage continues. If an enabled client’s torrent inventory is unavailable, all resumes are withheld because its download locations are unknown. Unresolved active download paths also withhold resumes across monitored storage. Unmatched paths are logged and left alone. Disabling/removing a monitor does not automatically resume torrents paused by it. Changes apply on the next processing cycle.

Migration to 6.20.3

Clients missing TorrentScanIntervalSeconds inherit the nearest allowed interval from the saved Settings.LoopSleepTimer. Values above 120 map to 120, below 5 to 5, and ties select the longer interval. Explicit valid values are preserved; unsupported explicit values are rejected. Migration saves config.toml.bak before persisting the result. New clients default to 30 seconds regardless of the database refresh interval.

Migration to 6.20.2

Maintenance remains the canonical per-client configuration and all ten tools remain supported. Configure them in Manage. Existing maintenance values, scopes, limits, outcomes, and schedules are preserved. Interim Storage and Recovery values fill only missing maintenance settings. Explicit daily cleanup becomes equivalent per-operation scheduling, without enabling unrelated tools. Schema 6.20.2 changes session execution modes to Manual while preserving their schedules. See Manage configuration.

Migration to 6.19.0

The old global CompletedDownloadFolder, FreeSpace, FreeSpaceFolder, AutoPauseResume, and FreeSpaceThresholdGB fields are migrated automatically, backed up to config.toml.bak, and removed from the saved file. Existing per-client values take precedence, including an explicitly empty monitor list.

For one client, a missing download root inherits the old completed folder (reverse-mapped only when unambiguous). The monitor uses the old free-space folder, completed folder, then mapped client download path. The old limit and disabled state are preserved. With multiple clients, explicit client paths are used; ambiguous paths remain disabled and produce warnings for review. Migration does not create path mappings.

Legacy TORRENTARR_SETTINGS_* environment overrides and their QBITRR_SETTINGS_* aliases still apply at runtime through equivalent conversion, without being written to disk. Explicitly empty primary variables suppress their aliases.

NoInternetSleepTimer

NoInternetSleepTimer = 15

Type: Integer (seconds) Default: 15

How long to wait when internet connection is lost before checking again.

Process:

  1. Torrentarr pings PingURLS to check connectivity
  2. If all pings fail, internet is considered down
  3. Torrentarr sleeps for NoInternetSleepTimer seconds
  4. Checks again

Recommendation: 15 for quick recovery, 60 for slower connections.

LoopSleepTimer — Database refresh interval

[Settings]
LoopSleepTimer = 3600  # Refresh the Arr catalog into SQLite once an hour

[TorrentClient.local]
TorrentScanIntervalSeconds = 30

Type: Integer or duration (seconds) Default: 5

Controls periodic Arr catalog synchronization into SQLite. It does not control torrent scans, free space protection, tracker sorting, failed/recheck processing, or search dispatch. Pause ownership, import results, recovery state, and search progress are persisted immediately when actions occur. Catalog sync runs at startup and after configuration changes, then follows this interval.

Search dispatch uses each Arr instance's EntrySearch.SearchRequestsEvery; nonpositive values permit continuous searches with a five-second dispatch floor. SearchLoopDelay remains the delay between individual search commands. RSS, refresh-download commands, connection recovery, maintenance schedules, and failure backoff retain their own timing.

SearchLoopDelay

SearchLoopDelay = -1

Type: Integer (seconds) Default: -1 (uses 30 seconds)

Controls the delay between individual search commands when processing a batch of searches within a single search loop.

How it works: - When set to -1 (default): Uses 30 seconds between each search command - When set to a positive value: Uses that many seconds between each search command - Applies to both missing media searches and request searches (Overseerr/Ombi)

Use cases: - Default (-1): Recommended for most setups - 30 second delay prevents overwhelming indexers - Lower values (5-15): For faster request processing with high-quality indexers - Higher values (60-120): For limited indexer API calls or rate-limited trackers

Example: If you have 10 missing movies to search: - SearchLoopDelay = -1 → 30 seconds between each movie search (5 minutes total) - SearchLoopDelay = 10 → 10 seconds between each movie search (1.7 minutes total) - SearchLoopDelay = 60 → 60 seconds between each movie search (10 minutes total)

Indexer Rate Limits

Setting this too low may trigger indexer rate limits. Most indexers allow 5-10 API calls per second, but spacing searches prevents hitting these limits.

Recommendation: Keep at -1 for the default 30-second delay, or adjust based on your indexer's rate limits.

FailedCategory

FailedCategory = "failed"

Type: String Default: "failed"

qBittorrent category for manually marking torrents as failed.

How to use:

  1. In qBittorrent, move a torrent to this category
  2. Torrentarr detects it on next loop
  3. Torrentarr marks it as failed in Arr
  4. Triggers re-search (if enabled)
  5. Removes torrent and files

Use cases:

  • Fake/corrupt files
  • Wrong content
  • Manual intervention needed

RecheckCategory

RecheckCategory = "recheck"

Type: String Default: "recheck"

qBittorrent category for forcing torrent recheck.

How to use:

  1. Move torrent to this category in qBittorrent
  2. Torrentarr forces a full recheck
  3. Moves torrent back to original category
  4. Continues normal processing

Use cases:

  • Fix "missing files" errors
  • After restoring from backup
  • After moving download location

Tagless

Tagless = false

Type: Boolean Default: false

Advanced feature: Manage torrents without requiring Arr tags.

When false (default):

  • Torrentarr uses both category and tags to identify torrents
  • More reliable
  • Recommended

When true:

  • Torrentarr uses only categories
  • Useful if Arr doesn't apply tags consistently
  • May cause conflicts if multiple Arr instances share categories

Recommendation: Keep false unless you have specific tagging issues.

IgnoreTorrentsYoungerThan

IgnoreTorrentsYoungerThan = 180

Type: Integer (seconds) Default: 180 (3 minutes)

Ignore torrents newer than this age for certain operations.

Applies to:

  • FailedCategory processing
  • RecheckCategory processing
  • Some health checks

Why?

  • Torrents need time to start
  • Prevents false "stalled" detection
  • Allows metadata to load

Recommendations:

  • 180 - (Default) 3 minutes
  • 120 - 2 minutes (faster)
  • 300 - 5 minutes (more conservative)

PingURLS

PingURLS = ["one.one.one.one", "dns.google.com"]

Type: Array of strings Default: ["one.one.one.one", "dns.google.com"]

Hostnames to ping for internet connectivity checks.

Requirements:

  • Must be reliable, always-online services
  • Must respond to ICMP pings or HTTP
  • Must tolerate frequent pings

Examples:

# Cloudflare and Google DNS
PingURLS = ["one.one.one.one", "dns.google.com"]

# Alternative DNS providers

PingURLS = ["1.1.1.1", "8.8.8.8", "9.9.9.9"]

# Mix of services

PingURLS = ["cloudflare.com", "google.com", "github.com"]

Recommendation: Keep at least 2 URLs for redundancy.

FFprobeAutoUpdate

FFprobeAutoUpdate = true

Type: Boolean Default: true

Automatically download and update FFprobe binary for media file validation.

When true:

  • Torrentarr downloads FFprobe from https://ffbinaries.com/downloads
  • Automatically updates to latest version
  • Stored in config directory (e.g. ~/config/ or ./config/); ffprobe path can be configured if needed

When false:

  • You must provide your own FFprobe binary
  • Place in config directory or system PATH (e.g. ~/config/ or ffprobe on PATH)

Recommendation: Keep true for automatic management.

AutoUpdateEnabled

AutoUpdateEnabled = false

Type: Boolean Default: false

Enable automatic Torrentarr updates on a schedule.

When true:

  • Torrentarr checks for updates on schedule (see AutoUpdateCron)
  • Downloads and installs latest version
  • Restarts automatically
  • Logs update in Main.log

Supported installation methods:

  • ✅ Native / binary (cron-driven apply downloads GitHub release asset)
  • ⚠️ Docker (prefer docker pull / Watchtower; in-container apply is optional)
  • ⚠️ dotnet run / dev trees (update manually)

Recommendation: For Docker, prefer image updates. For native installs, cron apply is optional; always back up config before enabling.

AutoUpdateChannel

AutoUpdateChannel = "latest"

Type: String Default: "latest" Allowed: "latest" | "stable" | "nightly"

Which GitHub release Torrentarr considers when checking for updates:

  • latest — newest GitHub release, including weekly dependency [build] tags.
  • stable — newest patch/minor/major release (skips prereleases and weekly X.Y.Z-N builds with N > 1; same rule as Docker :stable). X.Y.Z and X.Y.Z-1 stay eligible.
  • nightly — check and log only; do not download or apply binaries.

Source / dotnet run builds never apply binaries (TORRENTARR_SOURCE_BUILD / QBITRR_SOURCE_BUILD, a .git tree, or an unpublished bin/Debug|Release entry assembly).

Environment: TORRENTARR_SETTINGS_AUTO_UPDATE_CHANNEL (alias QBITRR_SETTINGS_AUTO_UPDATE_CHANNEL).

AutoUpdateCron

AutoUpdateCron = "0 3 * * 0"

Type: String (cron expression) Default: "0 3 * * 0" (Sundays at 3:00 AM)

Cron schedule for automatic updates (when AutoUpdateEnabled = true).

Cron format:

┌─ minute (0-59)
│ ┌─ hour (0-23)
│ │ ┌─ day of month (1-31)
│ │ │ ┌─ month (1-12)
│ │ │ │ ┌─ day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

Examples:

# Every Sunday at 3:00 AM
AutoUpdateCron = "0 3 * * 0"

# Every day at 2:00 AM

AutoUpdateCron = "0 2 * * *"

# Every Monday at 4:30 AM

AutoUpdateCron = "30 4 * * 1"

# First day of month at midnight

AutoUpdateCron = "0 0 1 * *"

Tools: Use crontab.guru to validate expressions.

AutoRestartProcesses

AutoRestartProcesses = true

Type: Boolean Default: true

Automatically restart crashed worker processes.

When true:

  • Crashed Arr manager processes restart automatically
  • Subject to restart limits (see below)
  • Prevents infinite crash loops

When false:

  • Crashed processes stay down
  • Only logs failures
  • Requires manual intervention

Recommendation: Keep true for automatic recovery.

MaxProcessRestarts

MaxProcessRestarts = 5

Type: Integer Default: 5

Maximum restart attempts per process within ProcessRestartWindow.

How it works:

  • Process crashes
  • Torrentarr restarts it after ProcessRestartDelay
  • If process crashes MaxProcessRestarts times within ProcessRestartWindow:
  • Auto-restart disabled for that process
  • Manual intervention required

Recommendation: 5 is safe. Increase if you have intermittent issues.

ProcessRestartWindow

ProcessRestartWindow = 300

Type: Integer (seconds) Default: 300 (5 minutes)

Time window for tracking restart attempts.

Example:

  • MaxProcessRestarts = 5
  • ProcessRestartWindow = 300
  • If a process restarts 5 times within 5 minutes, auto-restart stops

Recommendation: 300 (5 minutes) prevents crash loops while allowing recovery.

ProcessRestartDelay

ProcessRestartDelay = 5

Type: Integer (seconds) Default: 5

Wait time before attempting to restart a crashed process.

Why wait?

  • Gives system time to recover
  • Prevents immediate re-crash
  • Allows logs to flush

Recommendation: 5 is sufficient. Increase if processes crash immediately after restart.

WebUI Section

The [WebUI] section configures Torrentarr's web interface.

Complete WebUI Example

[WebUI]
Host = "0.0.0.0"
Port = 6969
Token = ""
AuthDisabled = true
LocalAuthEnabled = false
OIDCEnabled = false
Username = ""
PasswordHash = ""
LiveArr = true

Theme = "Dark"
ViewDensity = "Comfortable"

# Optional: when OIDCEnabled = true
# [WebUI.OIDC]
# Authority = "https://auth.example.com/application/o/myapp"
# ClientId = "your-client-id"
# ClientSecret = "your-client-secret"
# Scopes = "openid profile"
# CallbackPath = "/signin-oidc"
# RequireHttpsMetadata = true

Host

Host = "0.0.0.0"

Type: String (IP address) Default: "0.0.0.0"

IP address the WebUI listens on.

Options:

  • 0.0.0.0 - (Default) Listen on all interfaces
  • 127.0.0.1 - Localhost only (secure, but can't access remotely)
  • Specific IP - Listen on one network interface

Recommendation: 0.0.0.0 for Docker, 127.0.0.1 + reverse proxy for native.

Port

Port = 6969

Type: Integer Default: 6969

TCP port for the WebUI.

Access: http://<host>:<port>/ui

Examples:

Port = 6969   # http://localhost:6969/ui

Port = 8080   # http://localhost:8080/ui

Port = 443    # https://localhost:443/ui (with reverse proxy)

Token

Token = ""

Type: String Default: "" (empty, no authentication)

Bearer token for API authentication.

When empty:

  • WebUI and API are publicly accessible
  • No authentication required

When set:

  • All /api/* endpoints require authentication
  • Must include Authorization: Bearer header in requests

Setting up authentication:

[WebUI]
Token = "my-secret-token-12345"

Using authenticated API:

curl -H "Authorization: Bearer my-secret-token-12345" \
  http://localhost:6969/api/processes

Recommendation: Set a token if Torrentarr is accessible from the internet.

AuthDisabled, LocalAuthEnabled, OIDCEnabled

Type: Boolean Defaults: AuthDisabled = true, LocalAuthEnabled = false, OIDCEnabled = false

Control whether browser users must log in (local username/password and/or OIDC) or can access with token only. See WebUI Authentication for full authentication options and OIDC with Authentik for an example IdP setup.

Username, PasswordHash

Type: String Defaults: ""

Used for local auth when LocalAuthEnabled is true. PasswordHash stores only the hashed password (set via login page or POST /web/auth/set-password). See WebUI Authentication.

OIDC ([WebUI.OIDC])

Optional table when OIDCEnabled is true. Keys: Authority, ClientId, ClientSecret, Scopes, CallbackPath, RequireHttpsMetadata. See WebUI Authentication for full authentication and OIDC with Authentik for an example IdP setup.

LiveArr

LiveArr = true

Type: Boolean Default: true

Enable live updates in Arr views (Radarr/Sonarr/Lidarr tabs).

When true:

  • Real-time status updates
  • Progress bars update live
  • No manual refresh needed

When false:

  • Static snapshots
  • Must manually refresh page
  • Lower resource usage

Recommendation: Keep true for best UX.

Catalog grouping

Sonarr and Lidarr catalogs always browse as series and artist rows (qBitrr 5.14). The obsolete GroupSonarr / GroupLidarr keys are stripped on load and are not written back.

Theme

Theme = "Dark"

Type: String Default: "Dark" Options: Dark, Light

WebUI color theme.

  • Dark - Dark mode (easier on eyes)
  • Light - Light mode (better in bright environments)

Note: Users can toggle theme in the WebUI itself. This sets the default.

qBit Section

The [qBit] section configures the connection to qBittorrent.

Complete qBit Example

[qBit]
Disabled = false
DownloadPath = "/data/downloads"
FreeSpace = [{ Path = "/data/downloads", Enabled = true, Limit = "10G" }]
Host = "localhost"
Port = 8080
UserName = "admin"
Password = "adminpass"

For detailed qBittorrent configuration, see the qBittorrent Configuration Guide.

Arr Sections

Arr sections follow the naming pattern [<Type>-<Name>]:

  • [Radarr-Movies]
  • [Sonarr-TV]
  • [Lidarr-Music]
  • [Readarr-Books]

Each Arr instance has its own section with subsections for:

  • [<Type>-<Name>.Search] - Automated searching
  • [<Type>-<Name>.Overseerr] - Request integration (Radarr/Sonarr only)
  • [<Type>-<Name>.Torrent] - Torrent management
  • [<Type>-<Name>.Torrent.SeedingMode] - Seeding configuration
  • [[<Type>-<Name>.Torrent.Trackers]] - Per-tracker settings

For complete Arr configuration documentation:

Configuration Best Practices

1. Start with Example Config

# Generate example config
torrentarr --gen-config

# Copy to config location
cp config.example.toml ~/config/config.toml

2. Config file path (environment)

To point Torrentarr at a specific config file (e.g. in Docker):

# Path to config.toml file (QBITRR_CONFIG is also accepted)
export TORRENTARR_CONFIG=/config/config.toml

TORRENTARR_OVERRIDES_DATA_PATH (alias QBITRR_OVERRIDES_DATA_PATH) overrides the database/logs directory. TORRENTARR_OVERRIDES_SEARCH_ONLY / TORRENTARR_OVERRIDES_PROCESSING_ONLY (and QBITRR_* aliases) force search-only or processing-only mode.

Torrentarr also supports a small set of TORRENTARR_SETTINGS_* / TORRENTARR_QBIT_* env overrides (with QBITRR_* aliases). See Environment Variables.

3. Validate Your Config

Check for syntax errors with an online TOML validator (e.g. https://www.toml-lint.com/) or by starting Torrentarr and checking logs for config parse errors.

4. Backup Your Config

# Before major changes
cp ~/config/config.toml ~/config/config.toml.backup

# Automated backup (cron)
0 0 * * * cp ~/config/config.toml ~/config/config.toml.$(date +\%Y\%m\%d)

5. Version Control

# Initialize git repo
cd ~/config
git init
git add config.toml
git commit -m "Initial config"

# Track changes
git diff  # See what changed
git commit -am "Adjusted stall delay"

6. Security

Sensitive data in config:

# DON'T commit these to public repos
APIKey = "your-secret-key"
Password = "your-password"
Token = "your-token"

Use the WebUI Config Editor or edit config.toml for secrets. Torrentarr does not support per-key environment variable overrides; store secrets in config.toml with restricted file permissions or use the WebUI.

7. Documentation

Add comments to your config:

[Radarr-4K]
# Separate instance for 4K movies
# Uses higher quality profile and longer ETAs
MaximumETA = 172800  # 48 hours for large 4K files

Troubleshooting Config Issues

Config Not Loading

Symptoms: Torrentarr uses defaults or doesn't start

Solutions:

  1. Check file location: 

    # Native
ls -l ~/config/config.toml

# Docker
docker exec torrentarr ls -l /config/config.toml

  2. Check file permissions: 

    chmod 644 ~/config/config.toml

  3. Validate TOML syntax: Use an online TOML validator (e.g. https://www.toml-lint.com/) or start Torrentarr and check logs for config parse errors.

Invalid Value Errors

Symptoms: "Invalid value for X" errors in logs

Solutions:

  1. Check data types: 

    # Wrong
Port = "6969"  # String

# Right
Port = 6969    # Integer

  2. Check enums: 

    # Wrong
ConsoleLevel = "info"

# Right
ConsoleLevel = "INFO"

Changes Not Applied

Symptoms: Modified config not taking effect

Solution: Restart Torrentarr after config changes:

# Native
torrentarr --restart

# Docker
docker restart torrentarr

# Systemd
sudo systemctl restart torrentarr

Missing Required Values

Symptoms: "Missing required config key" errors

Solution: Check these are set:

[qBit]
Host = "localhost"  # Required
DownloadPath = "/path/to/downloads"  # Client-side root for category creation

Complete Minimal Config

Absolute minimum configuration to get started:

[Settings]
ConfigVersion = "6.20.3"

[WebUI]
Host = "0.0.0.0"
Port = 6969

[qBit]
Disabled = false
DownloadPath = "/data/downloads"
FreeSpace = [{ Path = "/data/downloads", Enabled = true, Limit = "10G" }]
Host = "localhost"
Port = 8080
UserName = "admin"
Password = "adminpass"

[Radarr-Movies]
Managed = true
URI = "http://localhost:7878"
APIKey = "your-radarr-api-key"
Category = "radarr-movies"
ReSearch = true

Advanced/Hidden Settings

These configuration options exist but are not generated by torrentarr --gen-config because they are intended for advanced troubleshooting only.

Settings.ProcessSpawnTimeoutSeconds

[Settings]
ProcessSpawnTimeoutSeconds = 60  # Increase if slow storage

Type: Integer (seconds) Default: 30 seconds Added manually to config

Timeout for spawning Arr instance worker processes during startup.

When to adjust:

  • Slow disk I/O (network storage, HDD)
  • High system load during startup
  • Database on slow filesystem

Behavior:

  • If process doesn't spawn within timeout, startup fails with error
  • Increase if seeing "Process spawn timed out" errors
  • Do NOT set below 10 seconds

Default is usually sufficient - only adjust if experiencing startup timeouts.

Edge Case Behaviors

Infinite Retry Loops

Torrentarr uses infinite retry loops in specific scenarios for reliability:

Quality Profile Fetching (Startup)

Location: Torrentarr.Infrastructure (Arr worker services) Behavior: Retries forever until Arr responds with quality profiles

Retry Strategy:

  • Network errors: Immediate retry
  • Server errors: Wait 5 minutes, retry
  • Unexpected errors: Give up

Why: Quality profiles are required for proper operation. Startup blocks until available.

Impact: Startup can hang if Arr is persistently unavailable. Check Arr logs if this occurs.

Search Command Posting

Location: Torrentarr.Infrastructure (Arr worker services) Behavior: Retries search API call until network succeeds

Retry Strategy:

  • ChunkedEncodingError: Retry immediately
  • ContentDecodingError: Retry immediately
  • ConnectionError: Retry immediately
  • JSONDecodeError: Retry immediately

Why: Ensures search commands are never lost due to transient network issues.

Impact: Search processing pauses during Arr downtime but resumes automatically when Arr recovers.

Note: Searched=True only set AFTER successful API call, so failed searches are retried.

Implementation Details (Not User-Configurable)

Database WAL Checkpoint

Torrentarr automatically performs WAL checkpoint and VACUUM on database errors for self-repair.

Not configurable - happens automatically during database error recovery.

See Database Troubleshooting for details on manual database maintenance.

TAGLESS Mode Exception

When Settings.Tagless = true, Torrentarr emulates tags using database entries EXCEPT for the special Torrentarr-ignored tag, which still uses a real qBittorrent tag.

Why: The ignore functionality requires a real tag to prevent Torrentarr from processing marked torrents.

This is intentional design, not a bug.

See Also