Docker Installation¶

Docker is the recommended way to run qBitrr. It provides an isolated, consistent environment that works across all platforms.

Prerequisites¶

Docker installed (Get Docker)
Docker Compose installed (optional but recommended)
qBittorrent running and accessible
At least one Arr instance (Radarr, Sonarr, or Lidarr)

Quick Start¶

Using Docker Run¶

docker run -d \
  --name qbitrr \
  --restart unless-stopped \
  -p 6969:6969 \
  -v /path/to/config:/config \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=America/New_York \
  feramance/qbitrr:latest

Using Docker Compose¶

Create a docker-compose.yml file:

version: "3.8"

services:
  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    restart: unless-stopped
    ports:
      - "6969:6969"
    volumes:
      - /path/to/config:/config
      - /path/to/downloads:/downloads  # Same as qBittorrent
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York

Then run:

docker-compose up -d

Configuration¶

Environment Variables¶

Variable	Default	Description
`PUID`	`1000`	User ID for file permissions
`PGID`	`1000`	Group ID for file permissions
`TZ`	`UTC`	Timezone (e.g., `America/New_York`, `Europe/London`)
`QBITRR_CONFIG_PATH`	`/config`	Path to config directory
`QBITRR_LOG_LEVEL`	`INFO`	Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)

Volume Mapping¶

Path Mapping is Critical

qBitrr, qBittorrent, and your Arr instances MUST all see the same paths for downloads. This is the #1 cause of issues with Docker setups.

Required volumes:

/config - Configuration files and database
/downloads - Must match qBittorrent and Arr download paths

Example:

If qBittorrent downloads to /downloads/torrents, and Radarr expects files in /downloads/torrents, then qBitrr needs the same mount:

services:
  qbittorrent:
    volumes:
      - /mnt/storage/downloads:/downloads

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

  qbitrr:
    volumes:
      - /mnt/storage/downloads:/downloads  # Same path!

Docker Compose Example (Complete)¶

Here's a complete example with qBittorrent, Radarr, and qBitrr:

version: "3.8"

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

  radarr:
    image: lscr.io/linuxserver/radarr:latest
    container_name: radarr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - /path/to/radarr/config:/config
      - /path/to/downloads:/downloads
      - /path/to/movies:/movies
    ports:
      - "7878:7878"
    restart: unless-stopped

  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - /path/to/qbitrr/config:/config
      - /path/to/downloads:/downloads  # Must match!
    ports:
      - "6969:6969"
    restart: unless-stopped
    depends_on:
      - qbittorrent
      - radarr

Image Tags¶

Tag	Description
`latest`	Latest stable release (recommended)
`nightly`	Latest development build (bleeding edge)
`5.x.x`	Specific version (e.g., `5.5.5`)

Recommended: Use latest for production, nightly for testing new features.

First Run¶

Start the container:
```
docker-compose up -d
```
Check logs:
```
docker logs -f qbitrr
```
Configuration file created: qBitrr will generate /config/config.toml on first run
Stop the container to edit config:
```
docker-compose down
```
Edit the configuration:
```
nano /path/to/config/config.toml
```
Start again:
```
docker-compose up -d
```

See the First Run Guide for detailed configuration steps.

Accessing the WebUI¶

Once running, access the WebUI at:

http://localhost:6969/ui

Or replace localhost with your server's IP address.

Updating¶

Docker Compose¶

docker-compose pull
docker-compose up -d

Docker Run¶

docker pull feramance/qbitrr:latest
docker stop qbitrr
docker rm qbitrr
# Run the docker run command again

Auto-Updates

qBitrr has a built-in auto-update feature that works in Docker. It will pull the latest image and restart the container automatically if configured.

Troubleshooting¶

Container Won't Start¶

Problem: Container exits immediately or fails to start

Check logs:

docker logs qbitrr

Common issues:

Port Already in Use

Error: bind: address already in use

Solution:

# Check what's using port 6969
sudo lsof -i :6969

# Change port in docker-compose.yml
ports:
  - "6970:6969"  # Map to different host port

Config Directory Permissions

PermissionError: [Errno 13] Permission denied: '/config'

Solution:

# Create directory with correct ownership
mkdir -p /path/to/config
sudo chown -R 1000:1000 /path/to/config
chmod -R 755 /path/to/config

Invalid config.toml Syntax

TOMLDecodeError: Invalid TOML

Solution:

# Validate TOML syntax
docker run --rm -v /path/to/config:/config \
  feramance/qbitrr:latest qbitrr --validate-config

# Or delete and regenerate
mv /path/to/config/config.toml /path/to/config/config.toml.old
docker restart qbitrr  # Generates new config

Missing Environment Variables
```
KeyError: 'QBITRR_CONFIG_PATH'
```
Solution: Ensure all required environment variables are set in docker-compose.yml

Can't Connect to qBittorrent/Arr¶

Problem: qBitrr can't reach qBittorrent or Arr instances

Diagnosis:

Check Container Communication:

# Ping qBittorrent from qBitrr
docker exec qbitrr ping -c 3 qbittorrent

# Check if port is reachable
docker exec qbitrr wget -O- http://qbittorrent:8080

Verify Network Configuration:

# Check which network containers are on
docker inspect qbitrr | grep NetworkMode
docker inspect qbittorrent | grep NetworkMode

# List all networks
docker network ls

Solutions:

Use Container Names (Same Network):

[Settings.Qbittorrent]
Host = "http://qbittorrent:8080"  # Use container name

[[Radarr]]
URI = "http://radarr:7878"  # Use container name

Use Host IP (Different Networks):

[Settings.Qbittorrent]
Host = "http://192.168.1.100:8080"  # Host IP

[[Radarr]]
URI = "http://192.168.1.100:7878"  # Host IP

Put All Containers on Same Network:

networks:
  media:
    driver: bridge

services:
  qbitrr:
    networks:
      - media
  qbittorrent:
    networks:
      - media
  radarr:
    networks:
      - media

Use host.docker.internal (Docker Desktop):

[Settings.Qbittorrent]
Host = "http://host.docker.internal:8080"

Permission Issues¶

Problem: Permission denied errors when accessing files

Symptoms:

PermissionError: [Errno 13] Permission denied
OSError: [Errno 1] Operation not permitted

Diagnosis:

Check Current PUID/PGID:

# On host
id yourusername
# Output: uid=1000(user) gid=1000(user)

# In container
docker exec qbitrr id

Check File Ownership:

ls -la /path/to/config
ls -la /path/to/downloads

Solutions:

Set Correct PUID/PGID:

environment:
  - PUID=1000  # Match your user's UID
  - PGID=1000  # Match your user's GID

Fix Existing File Permissions:

# Fix config directory
sudo chown -R 1000:1000 /path/to/config

# Fix downloads directory
sudo chown -R 1000:1000 /path/to/downloads

# Set proper permissions
chmod -R 775 /path/to/downloads

For NFS/SMB Shares:

volumes:
  - type: volume
    source: nfs-share
    target: /downloads
    volume:
      nocopy: true

volumes:
  nfs-share:
    driver: local
    driver_opts:
      type: nfs
      o: addr=192.168.1.100,rw,nfsvers=4
      device: ":/mnt/media/downloads"

Path Not Found Errors¶

Problem: qBitrr can't find downloaded files

Symptoms:

FileNotFoundError: [Errno 2] No such file or directory

Diagnosis:

# Check path in qBitrr
docker exec qbitrr ls -la /downloads

# Check same path in qBittorrent
docker exec qbittorrent ls -la /downloads

# Check same path in Radarr
docker exec radarr ls -la /downloads

# All should show the SAME files

Solutions:

Ensure Identical Volume Mappings:

services:
  qbittorrent:
    volumes:
      - /mnt/storage/downloads:/downloads  # Same host path

  radarr:
    volumes:
      - /mnt/storage/downloads:/downloads  # Same host path

  qbitrr:
    volumes:
      - /mnt/storage/downloads:/downloads  # Same host path

Check qBittorrent Save Path:
Open qBittorrent WebUI
Settings → Downloads
Default Save Path should be /downloads (or whatever you mapped)
Verify Remote Path Mapping in Arr:
Open Radarr/Sonarr
Settings → Download Clients → qBittorrent
Remote Path Mappings should be empty (if using same paths)
Or map qBittorrent's path to Arr's path if different

Import Failures¶

Problem: Downloads complete but don't import to Arr

Check qBitrr logs:

docker logs qbitrr | grep -i import

Check Arr logs:

docker logs radarr | grep -i import

Common Causes:

Path Mismatch:
qBittorrent sees: /downloads/Movie.mkv
Arr sees: /media/downloads/Movie.mkv
Fix: Use same volume mappings (see above)

Missing Instant Import:

[[Radarr]]
InstantImport = true  # Add this

FFprobe Validation Failed:

# Check logs for FFprobe errors
docker logs qbitrr | grep -i ffprobe

# Disable validation temporarily
# In config.toml:
[Settings]
FFprobeDownload = false

Category Not Configured:
qBittorrent assigns category: radarr
Arr download client category: movies (different!)
Fix: Match categories in both

Database Locked Errors¶

Problem: SQLite database locked errors in logs

Symptoms:

sqlite3.OperationalError: database is locked

Solutions:

Stop Multiple Instances:

# Check for multiple containers
docker ps --filter name=qbitrr

# Stop extras
docker stop qbitrr-old

Fix Permissions:

sudo chown 1000:1000 /path/to/config/qbitrr.db*
chmod 644 /path/to/config/qbitrr.db*

Repair Database:
```
docker exec qbitrr qbitrr --repair-db
```

Network Issues¶

Problem: Can't access WebUI or APIs

Check container is running:

docker ps | grep qbitrr

Check port mapping:

docker port qbitrr
# Should show: 6969/tcp -> 0.0.0.0:6969

Test from inside container:

docker exec qbitrr wget -O- http://localhost:6969/api/health

Test from host:

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

Solutions:

Firewall Blocking Port:

# Allow port 6969
sudo ufw allow 6969/tcp

# Or check firewalld
sudo firewall-cmd --add-port=6969/tcp --permanent
sudo firewall-cmd --reload

Wrong Bind Address:

[WebUI]
Host = "0.0.0.0"  # Listen on all interfaces
Port = 6969

Container Network Mode:

# Use bridge mode (default)
services:
  qbitrr:
    network_mode: bridge  # Not host

High CPU/Memory Usage¶

Problem: Container using too many resources

Check resource usage:

docker stats qbitrr

Solutions:

Set Resource Limits:

services:
  qbitrr:
    deploy:
      resources:
        limits:
          cpus: '1.0'      # Max 1 CPU core
          memory: 512M      # Max 512MB RAM
        reservations:
          cpus: '0.25'
          memory: 128M

Reduce Logging:

[Settings]
LogLevel = "INFO"  # Change from DEBUG

Increase Search Delay:

[Radarr.EntrySearch]
SearchRequestsEvery = 600  # Search less frequently

Optimize Database:
```
docker exec qbitrr qbitrr --vacuum-db
```

Auto-Update Not Working¶

Problem: Container doesn't auto-update

Docker auto-update requires:

Watchtower or similar:

services:
  watchtower:
    image: containrrr/watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    command: --interval 86400  # Check daily

Or enable qBitrr's built-in update:

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

Container Keeps Restarting¶

Problem: Container in restart loop

Check restart count:

docker ps -a | grep qbitrr

View last logs before crash:

docker logs --tail 100 qbitrr

Common Causes:

Config Error: Invalid TOML syntax
Fix: Validate config with --validate-config
Missing Dependencies: FFprobe download failed
Fix: Manually download FFprobe
Database Corruption:
Fix: Delete database, let qBitrr recreate

Disable auto-restart temporarily:

docker update --restart=no qbitrr

Advanced Configuration¶

Custom Network¶

Create a dedicated network for your media stack:

networks:
  media:
    driver: bridge

services:
  qbitrr:
    networks:
      - media
    # ... rest of config

Resource Limits¶

Limit CPU and memory usage:

services:
  qbitrr:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 512M

Health Checks¶

Add a health check:

services:
  qbitrr:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6969/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

Docker Compose Examples¶

Example 1: Complete Media Stack¶

Full stack with qBittorrent, Radarr, Sonarr, and qBitrr:

version: "3.8"

networks:
  media:
    driver: bridge

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

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

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

  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./qbitrr:/config
      - /mnt/storage/downloads:/downloads
    ports:
      - "6969:6969"
    networks:
      - media
    depends_on:
      - qbittorrent
      - radarr
      - sonarr
    restart: unless-stopped

Example 2: With Overseerr¶

Add request management:

version: "3.8"

networks:
  media:
    driver: bridge

services:
  # ... qbittorrent, radarr, sonarr from above ...

  overseerr:
    image: lscr.io/linuxserver/overseerr:latest
    container_name: overseerr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./overseerr:/config
    ports:
      - "5055:5055"
    networks:
      - media
    restart: unless-stopped

  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./qbitrr:/config
      - /mnt/storage/downloads:/downloads
    ports:
      - "6969:6969"
    networks:
      - media
    depends_on:
      - qbittorrent
      - radarr
      - sonarr
      - overseerr
    restart: unless-stopped

Example 3: With VPN¶

Run qBittorrent through VPN:

version: "3.8"

services:
  vpn:
    image: qmcgaw/gluetun
    container_name: vpn
    cap_add:
      - NET_ADMIN
    environment:
      - VPN_SERVICE_PROVIDER=nordvpn
      - VPN_TYPE=openvpn
      - OPENVPN_USER=your_username
      - OPENVPN_PASSWORD=your_password
      - SERVER_COUNTRIES=United States
    volumes:
      - ./gluetun:/gluetun
    ports:
      - "8080:8080"  # qBittorrent WebUI
      - "6881:6881"  # qBittorrent
      - "6881:6881/udp"
    restart: unless-stopped

  qbittorrent:
    image: lscr.io/linuxserver/qbittorrent:latest
    container_name: qbittorrent
    network_mode: "service:vpn"  # Route through VPN
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
      - WEBUI_PORT=8080
    volumes:
      - ./qbittorrent:/config
      - /mnt/storage/downloads:/downloads
    depends_on:
      - vpn
    restart: unless-stopped

  # radarr, sonarr, qbitrr don't need VPN
  radarr:
    image: lscr.io/linuxserver/radarr:latest
    # ... normal config, NOT through VPN

Example 4: With Traefik Reverse Proxy¶

version: "3.8"

networks:
  web:
    external: true
  media:
    driver: bridge

services:
  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    volumes:
      - ./qbitrr:/config
      - /mnt/storage/downloads:/downloads
    networks:
      - web
      - media
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.qbitrr.rule=Host(`qbitrr.yourdomain.com`)"
      - "traefik.http.routers.qbitrr.entrypoints=websecure"
      - "traefik.http.routers.qbitrr.tls.certresolver=letsencrypt"
      - "traefik.http.services.qbitrr.loadbalancer.server.port=6969"
    restart: unless-stopped

Best Practices¶

1. Use Named Volumes for Config¶

volumes:
  qbitrr-config:

services:
  qbitrr:
    volumes:
      - qbitrr-config:/config  # Persistent, managed by Docker
      - /mnt/storage/downloads:/downloads

2. Set Proper Restart Policies¶

services:
  qbitrr:
    restart: unless-stopped  # Don't restart if manually stopped

3. Use Health Checks¶

services:
  qbitrr:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:6969/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

4. Enable Logging Limits¶

services:
  qbitrr:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

5. Use Docker Secrets for API Keys¶

secrets:
  radarr_api_key:
    file: ./secrets/radarr_api_key.txt

services:
  qbitrr:
    secrets:
      - radarr_api_key
    environment:
      - RADARR_API_KEY_FILE=/run/secrets/radarr_api_key

Migration from Other Setups¶

From Native Install¶

Copy config:

cp ~/.config/qBitrr/config.toml /path/to/docker/config/

Copy database:

cp ~/.config/qBitrr/*.db /path/to/docker/config/

Update paths in config.toml:
Change /home/user/downloads to /downloads
Start Docker container

From Unraid¶

Add qBitrr from Community Applications
Map paths to match existing setup
Import existing config if desired

Performance Tips¶

1. Optimize Volume Performance¶

Use delegated/cached mounts on macOS:

volumes:
  - /mnt/storage/downloads:/downloads:delegated

2. Reduce Image Size¶

Use specific version tags:

image: feramance/qbitrr:5.5.5  # Not latest

3. Limit Log Output¶

environment:
  - QBITRR_LOG_LEVEL=INFO  # Not DEBUG

4. Use Local DNS¶

services:
  qbitrr:
    dns:
      - 1.1.1.1
      - 1.0.0.1
    extra_hosts:
      - "radarr:192.168.1.100"
      - "qbittorrent:192.168.1.100"

Next Steps¶

Ready to configure qBitrr?

Configure qBittorrent - qBittorrent Setup Guide
Configure Arr Instances - Arr Configuration Guide
First Run - Complete the First Run Setup
Troubleshooting - Docker-Specific Issues

Configuration File Reference - Complete TOML syntax
Environment Variables - All ENV vars
Path Mapping Guide - Fix path issues
Docker Troubleshooting - Comprehensive Docker guide
WebUI Access - Access the web interface

Docker Installation¶

Prerequisites¶

Quick Start¶

Using Docker Run¶

Using Docker Compose¶

Configuration¶

Environment Variables¶

Volume Mapping¶

Docker Compose Example (Complete)¶

Image Tags¶

First Run¶

Accessing the WebUI¶

Updating¶

Docker Compose¶

Docker Run¶

Troubleshooting¶

Container Won't Start¶

Can't Connect to qBittorrent/Arr¶

Permission Issues¶

Path Not Found Errors¶

Import Failures¶

Database Locked Errors¶

Network Issues¶

High CPU/Memory Usage¶

Auto-Update Not Working¶

Container Keeps Restarting¶

Advanced Configuration¶

Custom Network¶

Resource Limits¶

Health Checks¶

Docker Compose Examples¶

Example 1: Complete Media Stack¶

Example 2: With Overseerr¶

Example 3: With VPN¶

Example 4: With Traefik Reverse Proxy¶

Best Practices¶

1. Use Named Volumes for Config¶

2. Set Proper Restart Policies¶

3. Use Health Checks¶

4. Enable Logging Limits¶

5. Use Docker Secrets for API Keys¶

Migration from Other Setups¶

From Native Install¶

From Unraid¶

Performance Tips¶

1. Optimize Volume Performance¶

2. Reduce Image Size¶

3. Limit Log Output¶

4. Use Local DNS¶

Next Steps¶

Related Documentation¶