Frequently Asked Questions¶

General Questions¶

What is qBitrr?¶

qBitrr 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 qBitrr?¶

qBitrr solves several common problems:

Slow imports: Arr instances only scan for completed downloads every 1-15 minutes. qBitrr triggers imports instantly.
Stalled torrents: qBitrr detects and handles stuck downloads automatically.
Manual quality upgrades: qBitrr 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 qBitrr compatible with my setup?¶

qBitrr works with:

qBittorrent: v4.x and v5.x
Radarr: v3.x and v4.x
Sonarr: v3.x and v4.x
Lidarr: v1.x
Python: 3.11 or higher
Platforms: Linux, macOS, Windows, Docker

Installation Questions¶

Which installation method should I use?¶

Docker: Best for most users. Easy updates, isolated environment.
pip: Good if you're already using Python 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 qBitrr?¶

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! qBitrr fully supports running multiple instances of the same Arr type (e.g., Radarr-4K, Radarr-1080p, Sonarr-TV, Sonarr-Anime) in a single qBitrr installation.

How it works:

qBitrr 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 qBitrr 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:

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

Feature Questions¶

How does instant import work?¶

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

qBitrr 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 qBitrr 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, qBitrr marks it as failed, blacklists it in Arr, and triggers a new search.

How does automated search work?¶

qBitrr 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! qBitrr 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. qBitrr 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 qBitrr support private trackers?¶

Yes! qBitrr 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 qBitrr
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 qBitrr container
Arr instances need same path mapping
Use consistent paths across all containers

Example:

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

Docker path mapping →

Updates failing¶

Check these:

Installation type: qBitrr must detect git/pip/binary install correctly
Permissions: User running qBitrr 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:

[Settings]
WebUIToken = "your_secret_token_here"

Then add X-API-Token: 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 qBitrr?¶

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 qBitrr configuration?¶

Backup these files/folders:

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

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

Docker backup:

docker cp qbitrr:/config/config.toml ./config.toml.backup
docker cp qbitrr:/config/qBitrr.db ./qBitrr.db.backup

Can I run qBitrr on NAS devices?¶

Yes! qBitrr runs on many NAS platforms:

Synology: Docker or native Python
QNAP: Container Station (Docker)
Unraid: Community Applications
TrueNAS: Jails or Docker

NAS installation guide →

Does qBitrr work with VPN?¶

Yes, qBitrr works with VPN setups. Common configurations:

qBittorrent behind VPN: qBitrr 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 qBitrr 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

qBitrr'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 qBitrr 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
qBitrr 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]
EnableFFprobe = 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. qBitrr pauses all torrents 3. Arr imports completed downloads (frees space) 4. Space increases above threshold 5. qBitrr resumes torrents automatically

Disk space management →

Can I use qBitrr with Prowlarr?¶

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

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

They complement each other - no conflicts.

Does qBitrr support Usenet?¶

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

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

How do I migrate from another tool?¶

Common migrations:

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

From manual scripts: 1. Identify what scripts do 2. Configure equivalent qBitrr 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 qBitrr use them?¶

Custom Formats (CF) are Radarr/Sonarr scoring rules for releases. qBitrr 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 qBitrr 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 qBitrr support Windows?¶

Yes! Installation options:

Docker Desktop: Recommended for Windows
pip install: Requires Python 3.11+

Note: Pre-built binaries are not currently available. Use Docker or pip 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 qBitrr?¶

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 qBitrr with Plex/Jellyfin/Emby?¶

Yes! qBitrr works with any media server:

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

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

What's the performance impact of qBitrr?¶

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