Frequently Asked Questions¶

General Questions¶

What is Torrentarr?¶

Torrentarr is an automation tool that bridges qBittorrent with Radarr, Sonarr, and Lidarr. It monitors torrent health, triggers instant imports, automates searches, manages quality upgrades, and provides a modern web interface for complete control.

Why do I need Torrentarr?¶

Torrentarr solves several common problems:

Slow imports: Arr instances only scan for completed downloads every 1-15 minutes. Torrentarr triggers imports instantly.
Stalled torrents: Torrentarr detects and handles stuck downloads automatically.
Manual quality upgrades: Torrentarr can search for better releases automatically.
Request management: Integrates with Overseerr/Ombi to prioritize user requests.
Disk space issues: Automatically pauses torrents when disk space is low.

Is Torrentarr compatible with my setup?¶

Torrentarr works with:

qBittorrent: v4.x and v5.x
Radarr: v3.x and v4.x
Sonarr: v3.x and v4.x
Lidarr: v1.x
.NET: 8.0+ (for dotnet tool) or use Binary/Docker
Platforms: Linux, macOS, Windows, Docker

Installation Questions¶

Which installation method should I use?¶

Docker: Best for most users. Easy updates, isolated environment.
dotnet tool: Good if you have .NET 8+ or prefer native installs.
Systemd: Ideal for running as a Linux service.
Binary: Pre-built executables for advanced users.

Installation guides →

Can I run multiple instances of Torrentarr?¶

Yes, but each instance needs:

Its own config directory
Different port for WebUI (default: 6969)
Different Arr instances or categories to monitor

Can I configure multiple Arr instances of the same type?¶

Yes! Torrentarr fully supports running multiple instances of the same Arr type (e.g., Radarr-4K, Radarr-1080p, Sonarr-TV, Sonarr-Anime) in a single Torrentarr installation.

How it works:

Torrentarr maintains a single consolidated database for all Arr instances
Each instance's data is completely isolated using the ArrInstance field
Radarr-4K only sees 4K movies, Radarr-1080p only sees 1080p movies
Sonarr-TV only sees TV episodes, Sonarr-Anime only sees anime episodes
Each instance has its own search queue, profile mappings, and settings

Example configuration:

[Radarr-4K]
Category = "radarr-4k"
URI = "http://localhost:7878"
APIKey = "..."

[Radarr-1080p]
Category = "radarr-1080"
URI = "http://localhost:7879"
APIKey = "..."

[Sonarr-TV]
Category = "sonarr-tv"
URI = "http://localhost:8989"
APIKey = "..."

[Sonarr-Anime]
Category = "sonarr-anime"
URI = "http://localhost:8990"
APIKey = "..."

Benefits:

Separate quality profiles per use case (4K, 1080p, anime, etc.)
Independent search schedules and settings
Different seeding rules per category
Isolated upgrade searches
Single Torrentarr instance manages everything

Important: The Category field MUST be unique for each instance, and must match the download client category configured in your Arr instance.

Configuration Questions¶

Why aren't my torrents being monitored?¶

Check these common issues:

Categories don't match: Your Arr download client category must match the category configured in your Arr instance section
Missing tags: Arr downloads need tags configured
qBittorrent not connected: Check connection settings in [qBit] section
Wrong credentials: Verify username and password match qBittorrent settings

How do I find my Arr API key?¶

In Radarr/Sonarr/Lidarr:

Go to Settings → General
Scroll to "Security" section
Copy the "API Key" value

What categories should I use?¶

Default recommendations:

radarr-movies for Radarr
sonarr-tv for Sonarr
lidarr-music for Lidarr

These must match in:

Torrentarr config.toml
Arr download client configuration
qBittorrent category settings (optional)

Feature Questions¶

How does instant import work?¶

Torrentarr monitors qBittorrent for completed torrents. When a download finishes:

Torrentarr validates the files (optional FFprobe check)
Triggers DownloadedMoviesScan or DownloadedEpisodesScan in the Arr instance
Arr imports the files immediately (no waiting for periodic scan)

What is MaxETA?¶

MaxETA (Maximum Estimated Time of Arrival) is the longest time Torrentarr will wait for a torrent before marking it as failed. For example, MaximumETA = 604800 means 7 days. If a torrent won't finish within 7 days, Torrentarr marks it as failed, blacklists it in Arr, and triggers a new search.

How does automated search work?¶

Torrentarr can automatically search for:

Missing media: Movies/shows/albums not yet downloaded
Quality upgrades: Better releases for existing media
Custom format upgrades: Releases meeting minimum CF scores

Configure search in the Arr instance section of config.toml:

[Radarr-Movies.Search]
SearchMissing = true
SearchByYear = true
SearchInReverse = false
SearchLimit = 10

Can I use multiple Radarr/Sonarr instances?¶

Yes! Torrentarr fully supports multiple Arr instances of the same type (e.g., Radarr-4K and Radarr-1080p). Add multiple sections in config.toml:

[Radarr-Movies]
Category = "radarr-movies"
URI = "http://localhost:7878"
APIKey = "key1"

[Radarr-4K]
Category = "radarr-4k"
URI = "http://localhost:7879"
APIKey = "key2"

[Sonarr-TV]
Category = "sonarr-tv"
URI = "http://localhost:8989"
APIKey = "key3"

Each instance runs in its own process with completely isolated data. Torrentarr maintains a single consolidated database but uses the Category field to ensure each instance only sees its own movies/series/albums.

See FAQ: Can I configure multiple Arr instances of the same type? for detailed information about multi-instance data isolation.

Does Torrentarr support private trackers?¶

Yes! Torrentarr works with both public and private trackers. You can configure per-tracker settings for:

MaxETA thresholds
Ratio limits
Seeding time limits
Tag management

Tracker configuration →

Troubleshooting Questions¶

Imports aren't triggering¶

Common causes:

FFprobe validation failing: Check logs for media validation errors
File permissions: Arr instance can't read downloaded files
Path mapping: Paths don't match between qBittorrent, Arr, and Torrentarr
Category mismatch: Torrent category doesn't match config

Troubleshooting guide →

High CPU or memory usage¶

Reduce resource usage:

Increase loop sleep timers: SleepTimer in Arr instance config
Reduce search limits: Lower SearchLimit values
Disable verbose logging: Set log level to INFO or WARNING
Limit concurrent searches: Reduce SearchLimit per instance

Performance tuning →

Docker path issues¶

Ensure paths are accessible:

Mount qBittorrent download directory to Torrentarr container
Arr instances need same path mapping
Use consistent paths across all containers

Example:

torrentarr:
  volumes:
    - /downloads:/downloads  # Same as qBittorrent and Arr

Docker path mapping →

Updates failing¶

Check these:

Installation type: Torrentarr detects docker/dotnet/binary install for update behavior
Permissions: User running Torrentarr needs write access
GitHub API rate limit: Check if you're rate-limited
Docker: Pull new image instead of using built-in updater

Update troubleshooting →

WebUI Questions¶

What do the count numbers mean in the Arr views?¶

When viewing movies/series/albums in the WebUI, you'll see several count indicators:

Total: The total number of ALL items for this Arr instance (unfiltered)
Available: Number of items with files downloaded
Monitored: Number of items marked as monitored
Missing: Number of monitored items without files

Important: The "Total" count always shows ALL items in that Arr instance, regardless of any active filters (search, year range, quality met, etc.). This lets you see the true size of your library while filtering to specific subsets.

Example:

Radarr-4K has 500 movies total
Filter by year 2024: Shows 50 movies
Total still displays: 500 (not 50)

If you have multiple Arr instances of the same type (e.g., Radarr-4K and Radarr-1080p), each instance shows counts only for its own data. They are completely isolated from each other.

Can I change the WebUI port?¶

Yes, set in config.toml:

[Settings]
WebUIPort = 8080  # Default is 6969

How do I secure the WebUI?¶

Enable authentication:

[WebUI]
Token = "your_secret_token_here"

Then add Authorization: Bearer your_secret_token_here header to API requests.

Can I access WebUI remotely?¶

Yes, but secure it first:

Enable WebUIToken authentication
Use a reverse proxy (nginx, Caddy) with HTTPS
Don't expose port directly to the internet

Advanced Questions¶

Can I run custom scripts on events?¶

Not directly, but you can:

Monitor logs for specific events
Use Arr's "Custom Scripts" feature
Build webhooks using Arr's "Connect" feature

How do I contribute to Torrentarr?¶

See the Development Guide for:

Code style guidelines
Development setup
Pull request process
Testing requirements

Where can I request features?¶

GitHub Issues for bugs
GitHub Discussions for feature ideas

How do I backup my Torrentarr configuration?¶

Backup these files/folders:

# Essential
~/config/config.toml      # Configuration file
~/config/torrentarr.db        # Database

# Optional
~/config/logs/            # Log files (if needed)

Docker backup:

docker cp torrentarr:/config/config.toml ./config.toml.backup
docker cp torrentarr:/config/torrentarr.db ./torrentarr.db.backup

Can I run Torrentarr on NAS devices?¶

Yes! Torrentarr runs on many NAS platforms:

Synology: Docker or native binary/dotnet
QNAP: Container Station (Docker)
Unraid: Community Applications
TrueNAS: Jails or Docker

Docker installation guide → | Docker troubleshooting →

Does Torrentarr work with VPN?¶

Yes, Torrentarr works with VPN setups. Common configurations:

qBittorrent behind VPN: Torrentarr and Arr instances access qBit normally
All containers in VPN: Ensure proper network configuration
Split tunnel: Route only torrent traffic through VPN

The key is that Torrentarr must be able to reach qBittorrent and Arr instances on the network.

What's the difference between instant import and Arr's import?¶

Arr's default behavior: - Scans download folder every 1-15 minutes - Import delay: 1-15 minutes after download completes

Torrentarr's instant import: - Monitors qBittorrent events in real-time - Triggers import command immediately (within seconds) - Import delay: 5-10 seconds after download completes

Result: 2-15 minutes faster import to your library.

Can Torrentarr delete torrents automatically?¶

Yes, with seeding rules:

[Radarr-Movies.Torrent.SeedingMode]
MaxUploadRatio = 2.0          # Delete after 2.0 ratio
MaxSeedingTime = 604800       # Or after 7 days
RemoveTorrent = 3             # Remove when EITHER met

Options for RemoveTorrent: - -1 = Never remove - 1 = Remove when ratio met - 2 = Remove when time met - 3 = Remove when EITHER met - 4 = Remove when BOTH met

Seeding configuration →

How does FFprobe validation work?¶

FFprobe validates media files before import:

Download completes in qBittorrent
Torrentarr runs FFprobe to check file integrity
If valid: Trigger import to Arr
If invalid: Mark as failed, blacklist, re-search

Benefits: - Prevents importing corrupt files - Detects fake/sample files - Verifies codec compatibility

[Settings]
FFprobeAutoUpdate = true
FFprobeAutoUpdate = true  # Auto-download FFprobe

What happens when disk space is low?¶

With disk space management enabled:

[Settings]
FreeSpace = "50G"           # Threshold
FreeSpaceFolder = "/downloads"
AutoPauseResume = true

Behavior: 1. Disk space drops below 50GB 2. Torrentarr pauses all torrents 3. Arr imports completed downloads (frees space) 4. Space increases above threshold 5. Torrentarr resumes torrents automatically

Disk space management →

Can I use Torrentarr with Prowlarr?¶

Yes! Prowlarr manages indexers for Radarr/Sonarr/Lidarr. Torrentarr works alongside Prowlarr:

Prowlarr: Manages indexers, syncs to Arr instances
Torrentarr: Monitors torrents, triggers imports, automates searches

They complement each other - no conflicts.

Does Torrentarr support Usenet?¶

No, Torrentarr is specifically designed for torrents via qBittorrent. For Usenet:

Arr instances handle Usenet natively (SABnzbd/NZBGet)
Torrentarr only monitors qBittorrent categories

How do I migrate from another tool?¶

Common migrations:

From qBittorrent-Manager: 1. Install Torrentarr 2. Port your category/tag configuration 3. Disable old manager 4. Verify Torrentarr detects torrents

From manual scripts: 1. Identify what scripts do 2. Configure equivalent Torrentarr features 3. Test in parallel 4. Remove scripts once verified

Migration guide →

Can I customize search behavior?¶

Yes, extensive search customization:

[Radarr-Movies.EntrySearch]
SearchMissing = true              # Auto-search missing
SearchByYear = true               # Order by release year
SearchInReverse = false           # Newest first
SearchLimit = 10                  # Max concurrent
SearchRequestsEvery = 300         # Check every 5 min
DoUpgradeSearch = true            # Search for upgrades
CustomFormatUnmetSearch = true    # Enforce CF scores

Search configuration →

What are custom formats and how does Torrentarr use them?¶

Custom Formats (CF) are Radarr/Sonarr scoring rules for releases. Torrentarr can:

Enforce minimum scores: Remove torrents below threshold
Search for CF improvements: Find releases with better scores
Force quality standards: Block non-compliant releases

[Radarr-Movies.EntrySearch]
CustomFormatUnmetSearch = true     # Search for CF improvements
ForceMinimumCustomFormat = true    # Remove below threshold

Custom format guide →

How do I handle ratio requirements on private trackers?¶

Configure per-tracker seeding rules:

[[Radarr-Movies.Torrent.Trackers]]
Name = "PrivateHD"
URI = "https://tracker.privatehd.com"
MaxUploadRatio = 3.0      # Higher ratio for private
MaxSeedingTime = 1209600  # 14 days minimum
RemoveTorrent = 4         # Must meet BOTH requirements

This ensures you maintain good standing on private trackers.

Private tracker setup →

Can I schedule searches at specific times?¶

Currently, searches run on intervals:

SearchRequestsEvery = 300  # Every 5 minutes

For advanced scheduling, consider: - Using cron to restart Torrentarr at specific times - Adjusting intervals based on your indexer limits - Request integration for on-demand searches

How do I troubleshoot "No connection" errors?¶

For qBittorrent:

# Test connection
curl -u admin:password http://localhost:8080/api/v2/app/version

# Check if running
docker ps | grep qbittorrent

For Arr instances:

# Test API
curl -H "X-Api-Key: YOUR_KEY" http://localhost:7878/api/v3/system/status

# Check if running
docker ps | grep radarr

Common fixes: 1. Use container names in Docker (not localhost) 2. Verify ports are correct 3. Check firewall rules 4. Ensure services are running

Connection troubleshooting →

Does Torrentarr support Windows?¶

Yes! Installation options:

Docker Desktop: Recommended for Windows
dotnet tool: Requires .NET 8+

Note: Use Docker, dotnet tool, or binary installation methods.

Windows-specific notes: - Use Windows paths (e.g., C:\Downloads) - PowerShell or CMD for commands - Docker Desktop requires WSL2

Windows installation →

How often should I update Torrentarr?¶

Update frequency depends on your needs:

Stable releases: Every 1-2 months
Security updates: Immediately
Feature updates: When you need new features
Development builds: Only for testing

Enable auto-updates:

[Settings]
AutoUpdateEnabled = true
AutoUpdateCron = "0 3 * * 0"  # Sundays at 3 AM

Auto-update guide →

Can I use Torrentarr with Plex/Jellyfin/Emby?¶

Yes! Torrentarr works with any media server:

Torrentarr → manages qBittorrent torrents
Radarr/Sonarr/Lidarr → organizes media
Plex/Jellyfin/Emby → serves media to users

Torrentarr doesn't interact directly with media servers - it works through the Arr stack.

What's the performance impact of Torrentarr?¶

Typical resource usage:

CPU: 1-5% average (spikes during scans)
RAM: 100-300 MB
Disk: ~50 MB (application + database)
Network: Minimal (API calls only)

For 100+ torrents: - CPU: 5-10% during checks - RAM: 300-500 MB