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"

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

=== "pip"

```bash
qbitrr
```

=== "Systemd"

```bash
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"

```bash
docker stop qbitrr
```

=== "pip"

Press ++ctrl+c++ in the terminal

=== "Systemd"

```bash
sudo systemctl stop qbitrr
```

Step 3: Edit Configuration

Find and edit your config.toml file:

=== "Docker"

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

=== "pip"

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

=== "Systemd"

Location: Set via `Environment="QBITRR_OVERRIDES_DATA_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

!!! tip "Finding API Keys" - Radarr: Settings → General → Security → API Key - Sonarr: Settings → General → Security → API Key - Lidarr: Settings → General → Security → API Key

Step 4: Configure Categories & Tags

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

In qBittorrent

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

In Radarr/Sonarr/Lidarr

Go to Settings → Download Clients
Edit your qBittorrent client
Set the Category to match your config:
- Radarr: radarr-movies
- Sonarr: sonarr-tv
- Lidarr: lidarr-music
Add a Tag (e.g., qbitrr)
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"

```bash
docker start qbitrr
```

=== "pip"

```bash
qbitrr
```

=== "Systemd"

```bash
sudo systemctl start qbitrr
```

Step 6: Verify It's Working

Check Logs

=== "Docker"

```bash
docker logs -f qbitrr
```

=== "pip"

```bash
tail -f ~/logs/Main.log
```

=== "Systemd"

```bash
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

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

Step 7: Test with a Download

In Radarr/Sonarr/Lidarr, search for a movie/show/album
Manually grab a small torrent (for testing)
Watch qBitrr logs – it should detect the new torrent
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]
FFprobeAutoUpdate = 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:

[qBit]
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/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:

Check service is running:

docker ps | grep qbittorrent
netstat -tulpn | grep 8080

Use correct hostname:

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

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

Verify port mapping:
```
docker port qbittorrent
```

Issue: "Unauthorized" / 401 Error

Symptoms:

ERROR - qBittorrent authentication failed

Solutions:

Check credentials:

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

Test manually:

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

Reset qBittorrent password if forgotten

Issue: "Torrents not being monitored"

Symptoms: qBitrr runs but doesn't detect torrents

Solutions:

Verify category matches:

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

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

Check torrent has category:
- In qBittorrent, check torrent properties
- Category should show "radarr-movies"
Enable category in qBittorrent:
- Tools → Options → Downloads → Category
- Add "radarr-movies" category

Issue: "Imports not triggering"

Symptoms: Downloads complete but don't import to Arr

Solutions:

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

Verify file permissions:

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

Enable instant imports:

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

Check Radarr logs:
- Look for "Import failed" messages
- Common: Path mapping, permissions, file format issues

Issue: "FFprobe validation failed"

Symptoms:

WARNING - FFprobe validation failed for torrent XYZ

Solutions:

Let qBitrr download FFprobe:

[Settings]
FFprobeAutoUpdate = true
FFprobeAutoUpdate = true

Temporarily disable to test:
```
[Settings]
FFprobeAutoUpdate = false
```
Check file is complete:
- Torrent might still be downloading
- Wait for 100% completion

Issue: "High CPU usage"

Symptoms: qBitrr using excessive CPU

Solutions:

Increase check interval:

[Settings]
CheckInterval = 120  # Check every 2 minutes

Reduce concurrent checks:
```
[Settings]
MaxConcurrentChecks = 5
```
Disable FFprobe temporarily:
```
[Settings]
FFprobeAutoUpdate = false
```

Common Configuration Mistakes

Path Mismatches

Problem: qBittorrent saves to /downloads, but Radarr sees /data/downloads

Solution: Use consistent paths across all containers:

# docker-compose.yml — all services must mount the same path
qbittorrent:
  volumes:
    - /mnt/storage/downloads:/downloads
radarr:
  volumes:
    - /mnt/storage/downloads:/downloads
qbitrr:
  volumes:
    - /mnt/storage/downloads:/downloads

Wrong Category

Problem: Radarr uses radarr, but qBitrr config has radarr-movies

Solution: Ensure categories match exactly between your Arr download client configuration and qBitrr config.

Missing Tags

Problem: Torrents have tags but qBitrr has Tagless = false

Solution: Either enable tagless mode (Tagless = true) or configure matching tags in your Arr download clients.

Invalid API Keys

Problem: Copy-paste errors in API keys

Solution: Copy the entire key from Arr settings (Settings → General → Security), including any dashes or special characters.

What's Next?

Immediate Next Steps

Enable Automated Search:

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

Automated Search Guide →

Configure Health Monitoring:

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

Health Monitoring Guide →

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

Check logs for errors:
```
docker logs qbitrr | grep ERROR
```
Verify configuration:
- URLs are correct
- API keys are valid
- Categories match exactly
Search existing issues:
- GitHub Issues
- Discussions

Where to Get Help

📚 Troubleshooting Guide - Detailed solutions
❓ FAQ - Common questions
💬 GitHub Discussions - Community support
🐛 GitHub Issues - Bug reports

Creating a Support Request

Include:

Environment:

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

Problem description:
- What you expected
- What actually happened
- Steps to reproduce
Relevant logs:
```
docker logs qbitrr 2>&1 | tail -100
```

Configuration (redact sensitive info):

[qBit]
Host = "http://qbittorrent:8080"
Username = "admin"
Password = "REDACTED"

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

Uh oh!

FilesExpand file tree

quickstart.md

Latest commit

History

quickstart.md

File metadata and controls

Quick Start Guide

Prerequisites

Step 1: Start qBitrr

Step 2: Stop qBitrr

Step 3: Edit Configuration

Minimal Configuration

Step 4: Configure Categories & Tags

In qBittorrent

In Radarr/Sonarr/Lidarr

In qBitrr config.toml

Step 5: Start qBitrr Again

Step 6: Verify It's Working

Check Logs

Access the WebUI

Step 7: Test with a Download

Common Quick Start Scenarios

Scenario 1: Simple Home Server

Scenario 2: Multi-Arr Setup

Scenario 3: Power User with Quality Control

Scenario 4: Docker Compose Full Stack

Configuration Checklist

qBittorrent Configuration

Arr Configuration

Network Configuration

Verification Commands

Test qBittorrent Connection

Test Radarr Connection

Test Sonarr Connection

Test qBitrr WebUI

Common First-Run Issues

Issue: "Connection refused"

Issue: "Unauthorized" / 401 Error

Issue: "Torrents not being monitored"

Issue: "Imports not triggering"

Issue: "FFprobe validation failed"

Issue: "High CPU usage"

Common Configuration Mistakes

Path Mismatches

Wrong Category

Missing Tags

Invalid API Keys

What's Next?

Immediate Next Steps

Advanced Configuration

Explore WebUI

Getting Help

Before Asking for Help

Where to Get Help

Creating a Support Request