Skip to content

Quick Start Guide

Get qBitrr running in 5 minutes!

Prerequisites

  • qBittorrent installed and running
  • At least one Arr instance (Radarr, Sonarr, or Lidarr)
  • qBitrr installed (installation guide)

Step 1: Start qBitrr

docker run -d \
  --name qbitrr \
  -p 6969:6969 \
  -v /path/to/config:/config \
  feramance/qbitrr:latest

qbitrr

sudo systemctl start qbitrr

On first run, qBitrr will generate a default config.toml file.

Step 2: Stop qBitrr

Stop qBitrr so you can edit the configuration:

docker stop qbitrr

Press Ctrl+C in the terminal

sudo systemctl stop qbitrr

Step 3: Edit Configuration

Find and edit your config.toml file:

Location: /path/to/config/config.toml (where you mounted /config)

Location: ~/config/config.toml (home directory)

Location: Set via Environment="QBITRR_CONFIG_PATH=/path/to/config" in service file

Minimal Configuration

Here's the minimum configuration needed:

[qBit]
Host = "localhost"              # Your qBittorrent host
Port = 8080                     # qBittorrent WebUI port
UserName = "admin"              # qBittorrent username
Password = "adminpass"          # qBittorrent password

[Radarr-Movies]  # Or Sonarr-TV, Lidarr-Music
URI = "http://localhost:7878"  # Your Radarr URL
APIKey = "your_radarr_api_key"  # From Radarr Settings > General > Security

Finding API Keys

  • Radarr: Settings → General → Security → API Key
  • Sonarr: Settings → General → Security → API Key
  • Lidarr: Settings → General → Security → API Key

Multi-qBittorrent Support (v3.0+)

qBitrr can now manage torrents across multiple qBittorrent instances!

To add additional instances, use the [qBit-NAME] syntax in your config:

[qBit]  # Default instance (required)
Host = "localhost"
Port = 8080
UserName = "admin"
Password = "password"

[qBit-seedbox]  # Additional instance (optional)
Host = "192.168.1.100"
Port = 8080
UserName = "admin"
Password = "seedboxpass"

See qBittorrent Configuration for complete details.

Step 4: Configure Categories & Tags

qBitrr requires your Arr downloads to be tagged so it knows which torrents to monitor.

In qBittorrent

  1. Go to Tools → Options → Downloads
  2. Set "Default Save Path" categories:
  3. radarr-movies for Radarr downloads
  4. sonarr-tv for Sonarr downloads
  5. lidarr-music for Lidarr downloads

In Radarr/Sonarr/Lidarr

  1. Go to Settings → Download Clients
  2. Edit your qBittorrent client
  3. Set the Category to match your config:
  4. Radarr: radarr-movies
  5. Sonarr: sonarr-tv
  6. Lidarr: lidarr-music
  7. Add a Tag (e.g., qbitrr)
  8. Save

In qBitrr config.toml

Make sure your category names match:

[Settings]
CategoryRadarr = "radarr-movies"
CategorySonarr = "sonarr-tv"
CategoryLidarr = "lidarr-music"

Step 5: Start qBitrr Again

docker start qbitrr

qbitrr

sudo systemctl start qbitrr

Step 6: Verify It's Working

Check Logs

docker logs -f qbitrr

tail -f ~/logs/Main.log

sudo journalctl -u qbitrr -f

Look for these messages:

  • ✅ Connecting to qBittorrent...
  • ✅ Connecting to Radarr/Sonarr/Lidarr...
  • ✅ Starting Arr manager process...
  • ❌ Failed to connect... (fix your URL/API key)

Access the WebUI

  1. Open your browser to http://localhost:6969/ui
  2. Go to the Processes tab
  3. You should see your Arr manager(s) running

Step 7: Test with a Download

  1. In Radarr/Sonarr/Lidarr, search for a movie/show/album
  2. Manually grab a small torrent (for testing)
  3. Watch qBitrr logs – it should detect the new torrent
  4. When the download completes, qBitrr will trigger an import

Common Quick Start Scenarios

Scenario 1: Simple Home Server

Setup: Single Radarr for movies, basic monitoring

Time: 10 minutes

[qBit]
Host = "localhost"
Port = 8080
UserName = "admin"
Password = "adminpass"

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

What You Get: - ✅ Automatic torrent health monitoring - ✅ Instant imports when downloads complete - ✅ Automatic re-search on failed downloads - ✅ WebUI for monitoring

Scenario 2: Multi-Arr Setup

Setup: Radarr + Sonarr + Lidarr, full automation

Time: 20 minutes

[qBit]
Host = "localhost"
Port = 8080
UserName = "admin"
Password = "adminpass"

[Settings]
# Global settings
CompletedDownloadFolder = "/downloads"
FreeSpace = "50G"  # Pause when less than 50GB free
AutoPauseResume = true

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

[Radarr-Movies.EntrySearch]
SearchMissing = true
SearchLimit = 5
SearchByYear = true

[Sonarr-TV]
URI = "http://localhost:8989"
APIKey = "sonarr-api-key"
Category = "sonarr-tv"
Managed = true
ReSearch = true

[Sonarr-TV.EntrySearch]
SearchMissing = true
PrioritizeTodaysReleases = true
SearchBySeries = "smart"

[Lidarr-Music]
URI = "http://localhost:8686"
APIKey = "lidarr-api-key"
Category = "lidarr-music"
Managed = true
ReSearch = true

What You Get: - ✅ All three Arr types managed - ✅ Automated search for missing content - ✅ Disk space management - ✅ Today's TV episodes prioritized - ✅ Smart series vs episode search

Scenario 3: Power User with Quality Control

Setup: Radarr 4K + 1080p, Sonarr, Custom Formats

Time: 45 minutes

[qBit]
Host = "qbittorrent"  # Docker container name
Port = 8080
UserName = "admin"
Password = "secure-password-here"

[Settings]
EnableFFprobe = true  # Validate files before import
FFprobeAutoUpdate = true

# Radarr for 4K movies
[Radarr-4K]
URI = "http://radarr-4k:7879"
APIKey = "radarr-4k-api-key"
Category = "radarr-4k"
Managed = true
importMode = "Copy"  # Keep seeding

[Radarr-4K.EntrySearch]
SearchMissing = true
DoUpgradeSearch = true
CustomFormatUnmetSearch = true
ForceMinimumCustomFormat = true
SearchLimit = 3

[Radarr-4K.Torrent]
MaximumETA = 86400  # 24 hours
StalledDelay = 30
FileExtensionAllowlist = [".mkv", ".mp4", ".!qB", ".parts"]

[Radarr-4K.Torrent.SeedingMode]
MaxUploadRatio = 3.0
MaxSeedingTime = 1209600  # 14 days
RemoveTorrent = 4  # Both ratio AND time

# Radarr for 1080p movies
[Radarr-HD]
URI = "http://radarr:7878"
APIKey = "radarr-hd-api-key"
Category = "radarr-hd"
Managed = true
importMode = "Move"

[Radarr-HD.EntrySearch]
SearchMissing = true
SearchLimit = 10

# Sonarr for TV
[Sonarr-TV]
URI = "http://sonarr:8989"
APIKey = "sonarr-api-key"
Category = "sonarr-tv"
Managed = true

[Sonarr-TV.EntrySearch]
SearchMissing = true
PrioritizeTodaysReleases = true
AlsoSearchSpecials = false
SearchBySeries = "smart"

What You Get: - ✅ Separate 4K and HD libraries - ✅ FFprobe validation for file integrity - ✅ Custom format enforcement - ✅ Quality upgrade searches - ✅ Per-library seeding rules - ✅ Automated search for missing content

Scenario 4: Docker Compose Full Stack

Setup: Complete media stack with Overseerr

Time: 30 minutes

docker-compose.yml: 

version: '3.8'

services:
  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent/config:/config
      - /mnt/storage/downloads:/downloads
    ports:
      - "8080:8080"
      - "6881:6881"
    restart: unless-stopped

  radarr:
    image: linuxserver/radarr:latest
    container_name: radarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./radarr/config:/config
      - /mnt/storage:/storage
    ports:
      - "7878:7878"
    restart: unless-stopped

  sonarr:
    image: linuxserver/sonarr:latest
    container_name: sonarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./sonarr/config:/config
      - /mnt/storage:/storage
    ports:
      - "8989:8989"
    restart: unless-stopped

  overseerr:
    image: sctx/overseerr:latest
    container_name: overseerr
    environment:
      - LOG_LEVEL=info
      - TZ=America/New_York
    ports:
      - "5055:5055"
    volumes:
      - ./overseerr/config:/app/config
    restart: unless-stopped

  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./qbitrr/config:/config
      - /mnt/storage:/storage  # Same as Arr instances
    ports:
      - "6969:6969"
    depends_on:
      - qbittorrent
      - radarr
      - sonarr
    restart: unless-stopped

qBitrr config.toml: 

[Settings.Qbittorrent]
Host = "http://qbittorrent:8080"  # Use container names
Username = "admin"
Password = "adminpass"

[Settings]
CompletedDownloadFolder = "/storage/downloads"

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

[Radarr-Movies.EntrySearch.Overseerr]
SearchOverseerrRequests = true
OverseerrURI = "http://overseerr:5055"
OverseerrAPIKey = "your-overseerr-api-key"
ApprovedOnly = true
Is4K = false

[Sonarr-TV]
URI = "http://sonarr:8989"
APIKey = "your-sonarr-api-key"
Category = "sonarr-tv"
Managed = true

[Sonarr-TV.EntrySearch.Overseerr]
SearchOverseerrRequests = true
OverseerrURI = "http://overseerr:5055"
OverseerrAPIKey = "your-overseerr-api-key"
ApprovedOnly = true

What You Get: - ✅ Complete Docker stack with consistent paths - ✅ Overseerr integration for requests - ✅ Automatic container dependencies - ✅ Easy backup (just copy folders) - ✅ Network isolation

Configuration Checklist

Before starting, verify:

qBittorrent Configuration

  • WebUI enabled (Tools → Options → Web UI)
  • Authentication configured (username/password)
  • Default save path set
  • Categories created for each Arr instance

Arr Configuration

  • API key available (Settings → General → Security)
  • qBittorrent download client added
  • Category set in download client
  • Optional: Tags configured
  • Root folders configured
  • Quality profiles set up

Network Configuration

  • All services can reach each other
  • Ports not blocked by firewall
  • Docker networks configured (if using Docker)
  • Path mappings consistent across services

Verification Commands

Test your setup with these commands:

Test qBittorrent Connection

# From qBitrr container/host
curl -u admin:adminpass http://qbittorrent:8080/api/v2/app/version

# Expected: {"version":"4.6.0"} or similar

Test Radarr Connection

curl -H "X-Api-Key: your-api-key" http://radarr:7878/api/v3/system/status

# Expected: JSON with version, branch, etc.

Test Sonarr Connection

curl -H "X-Api-Key: your-api-key" http://sonarr:8989/api/v3/system/status

# Expected: JSON with version, branch, etc.

Test qBitrr WebUI

curl http://localhost:6969/api/health

# Expected: {"status":"healthy","version":"5.5.5"}

Common First-Run Issues

Issue: "Connection refused"

Symptoms: 

ERROR - Failed to connect to qBittorrent at http://localhost:8080

Solutions:

  1. Check service is running: 

    docker ps | grep qbittorrent
netstat -tulpn | grep 8080

  2. Use correct hostname: 

    # Docker: Use container name
Host = "http://qbittorrent:8080"

# Native: Use localhost or IP
Host = "http://localhost:8080"

  3. Verify port mapping: 

    docker port qbittorrent

Issue: "Unauthorized" / 401 Error

Symptoms: 

ERROR - qBittorrent authentication failed

Solutions:

  1. Check credentials: 

    Username = "admin"  # Must match qBittorrent
Password = "adminpass"  # Case-sensitive!

  2. Test manually: 

    curl -u admin:adminpass http://localhost:8080/api/v2/app/version

  3. Reset qBittorrent password if forgotten

Issue: "Torrents not being monitored"

Symptoms: qBitrr runs but doesn't detect torrents

Solutions:

  1. Verify category matches: 

    # qBitrr config
[Radarr-Movies]
Category = "radarr-movies"

# Radarr download client
# Category must be exactly "radarr-movies"

  2. Check torrent has category:

  3. In qBittorrent, check torrent properties

  4. Category should show "radarr-movies"

  5. Enable category in qBittorrent:

  6. Tools → Options → Downloads → Category
  7. Add "radarr-movies" category

Issue: "Imports not triggering"

Symptoms: Downloads complete but don't import to Arr

Solutions:

  1. Check path mapping: 

    # All services must see same paths
qbittorrent:
  volumes:
    - /mnt/storage/downloads:/downloads

radarr:
  volumes:
    - /mnt/storage/downloads:/downloads

qbitrr:
  volumes:
    - /mnt/storage/downloads:/downloads

  2. Verify file permissions: 

    ls -la /downloads/radarr-movies/
# Files should be readable by Radarr user

  3. Enable instant imports: 

    [Radarr-Movies]
InstantImport = true  # Default is true

  4. Check Radarr logs:

  5. Look for "Import failed" messages
  6. Common: Path mapping, permissions, file format issues

Issue: "FFprobe validation failed"

Symptoms: 

WARNING - FFprobe validation failed for torrent XYZ

Solutions:

  1. Let qBitrr download FFprobe: 

    [Settings]
EnableFFprobe = true
FFprobeAutoUpdate = true

  2. Temporarily disable to test: 

    [Settings]
EnableFFprobe = false

  3. Check file is complete:

  4. Torrent might still be downloading
  5. Wait for 100% completion

Issue: "High CPU usage"

Symptoms: qBitrr using excessive CPU

Solutions:

  1. Increase check interval: 

    [Settings]
CheckInterval = 120  # Check every 2 minutes

  2. Reduce concurrent checks: 

    [Settings]
MaxConcurrentChecks = 5

  3. Disable FFprobe temporarily: 

    [Settings]
EnableFFprobe = false

What's Next?

Immediate Next Steps

  1. Enable Automated Search: 

    [Radarr-Movies.EntrySearch]
SearchMissing = true
SearchLimit = 5
SearchByYear = true
    Automated Search Guide →

  2. Configure Health Monitoring: 

    [Radarr-Movies.Torrent]
MaximumETA = 86400  # 24 hours
StalledDelay = 15   # 15 minutes
ReSearchStalled = true
    Health Monitoring Guide →

  3. Set Up Seeding Rules: 

    [Radarr-Movies.Torrent.SeedingMode]
MaxUploadRatio = 2.0
MaxSeedingTime = 604800  # 7 days
RemoveTorrent = 3  # Either condition met
    Seeding Configuration →

Advanced Configuration

Explore WebUI

Access your qBitrr WebUI at http://localhost:6969/ui to:

  • Monitor processes in real-time
  • View logs with filtering
  • Browse Arr libraries
  • Edit configuration
  • Check system status

WebUI Documentation →

Getting Help

Before Asking for Help

  1. Check logs for errors: 

    docker logs qbitrr | grep ERROR

  2. Verify configuration:

  3. URLs are correct
  4. API keys are valid

  5. Categories match exactly

  6. Search existing issues:

  7. GitHub Issues
  8. Discussions

Where to Get Help

Creating a Support Request

Include:

  1. Environment: 

    qBitrr version: 5.5.5
Installation method: Docker
OS: Ubuntu 22.04
qBittorrent: 4.6.0
Radarr: 5.0.0

  2. Problem description:

  3. What you expected
  4. What actually happened

  5. Steps to reproduce

  6. Relevant logs: 

    docker logs qbitrr 2>&1 | tail -100

  7. Configuration (redact sensitive info): 

    [Settings.Qbittorrent]
Host = "http://qbittorrent:8080"
Username = "admin"
Password = "REDACTED"

Congratulations! 🎉 You've successfully set up qBitrr. Happy automating!