feramance/qbitrr

qBitrr

https://github.com/Feramance/Torrentarr – Companion tools and automation for the *Arr ecosystem.

https://img.shields.io/pypi/v/qBitrr2?label=PyPI](https://pypi.org/project/qBitrr2/) https://img.shields.io/pypi/dm/qBitrr2](https://pypi.org/project/qBitrr2/) https://img.shields.io/docker/pulls/feramance/qbitrr.svg](https://hub.docker.com/r/feramance/qbitrr) https://github.com/Feramance/qBitrr/actions/workflows/codeql.yml/badge.svg?branch=master](https://github.com/Feramance/qBitrr/actions/workflows/codeql.yml) https://github.com/Feramance/qBitrr/actions/workflows/nightly.yml/badge.svg?branch=master](https://github.com/Feramance/qBitrr/actions/workflows/nightly.yml) 

🧩 The intelligent glue between qBittorrent and the *Arr ecosystem (Radarr, Sonarr, Lidarr). Monitors torrent health, triggers instant imports, automates quality upgrades, manages disk space, integrates with request systems (Overseerr/Ombi), and provides a modern React dashboard for complete visibility and control.

📚 Documentation

Full documentation is available at: https://feramance.github.io/qBitrr/

• https://feramance.github.io/qBitrr/getting-started/ – Installation guides for pip, Docker, and native setups
• https://feramance.github.io/qBitrr/configuration/ – qBittorrent, Arr instances, quality profiles, and more
• https://feramance.github.io/qBitrr/features/ – Health monitoring, automated search, quality management, disk space, auto-updates
• https://feramance.github.io/qBitrr/webui/ – Built-in React dashboard with live monitoring and config editor
• https://feramance.github.io/qBitrr/troubleshooting/ – Common issues and debug logging
• https://feramance.github.io/qBitrr/webui/api/ – REST API documentation

⚡ Quick Start

🐍 Install with pip

bash
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install qBitrr2

# First run creates config (Docker: /config/config.toml; native: .config/config.toml in current directory, or set QBITRR_OVERRIDES_DATA_PATH)
qbitrr

🐳 Run with Docker

bash
docker run -d \
  --name qbitrr \
  --tty \
  -e TZ=Europe/London \
  -p 6969:6969 \
  -v /path/to/appdata/qbitrr:/config \
  -v /path/to/completed/downloads:/completed_downloads:rw \
  --restart unless-stopped \
  feramance/qbitrr:latest

Docker Compose:

yaml
services:
  qbitrr:
    image: feramance/qbitrr:latest
    container_name: qbitrr
    restart: unless-stopped
    tty: true
    environment:
      TZ: Europe/London
    ports:
      - "6969:6969"
    volumes:
      - /path/to/appdata/qbitrr:/config
      - /path/to/completed/downloads:/completed_downloads:rw

Access the WebUI at http://<host>:6969/ui after startup.

✨ Key Features

• 🚀 Multi-qBittorrent Support (v5.7.x+) – Manage torrents across multiple qBittorrent instances for load balancing, redundancy, and *** isolation
• 🚑 Torrent Health Monitoring – Detect stalled/failed downloads, auto-blacklist, trigger re-searches
• 🔍 Automated Search – Missing media, quality upgrades, custom format scoring
• 🎯 Request Integration – Pull requests from Overseerr/Ombi, prioritize user-requested media
• 📊 Quality Management – RSS sync, queue refresh, profile switching, custom format enforcement
• 🌱 Seeding Control – Per-tracker settings, ratio/time limits, tracker injection
• 🛡️ Hit and Run Protection – Automatic HnR obligation tracking with configurable thresholds, partial download handling, and dead tracker bypass
• 💾 Disk Space Management – Auto-pause when low on space, configurable thresholds
• 🔄 Auto-Updates – GitHub release-based updates with scheduled cron support
• 💻 Modern WebUI – Live process monitoring, log viewer, Arr insights, config editor

🛠️ Essential Configuration

1. Configure qBittorrent in your config file (Docker: /config/config.toml; native: .config/config.toml in the current directory, or path set by QBITRR_OVERRIDES_DATA_PATH):

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

2. Add Arr instances:

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

3. Set completed folder:

   toml
   [Settings]
   CompletedDownloadFolder = "/path/to/completed"
   

🆕 Multi-qBittorrent (v5.7.x+)

Manage torrents across multiple qBittorrent instances:

toml
[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 https://github.com/Feramance/qBitrr/blob/master/docs/configuration/qbittorrent.md (multi-instance section) for complete documentation.

See https://feramance.github.io/qBitrr/configuration/ and https://github.com/Feramance/qBitrr/blob/master/config.example.toml for all available options.

📖 Resources

• Documentation: https://feramance.github.io/qBitrr/
• PyPI Package: https://pypi.org/project/qBitrr2/
• Docker Hub: https://hub.docker.com/r/feramance/qbitrr
• Example Config: https://github.com/Feramance/qBitrr/blob/master/config.example.toml
• API Documentation: https://github.com/Feramance/qBitrr/blob/master/docs/webui/api.md
• Systemd Setup: https://github.com/Feramance/qBitrr/blob/master/docs/getting-started/installation/systemd.md

🐛 Issues & Support

• Report Bugs: https://github.com/Feramance/qBitrr/blob/master/.github/ISSUE_TEMPLATE/bug_report.yml
• Request Features: https://github.com/Feramance/qBitrr/blob/master/.github/ISSUE_TEMPLATE/feature_request.yml
• Discussions: https://github.com/Feramance/qBitrr/discussions
• Troubleshooting: https://feramance.github.io/qBitrr/troubleshooting/

🤝 Contributing

Contributions welcome! See https://github.com/Feramance/qBitrr/blob/master/docs/development/contributing.md for coding guidelines and development setup.

Development setup:

bash
# Python backend
make newenv && make syncenv
make reformat  # Format and lint

# WebUI
cd webui && npm ci
npm run dev    # Dev server at localhost:5173

❤️ Support

If qBitrr saves you time and headaches:

• ⭐ Star the repo – helps others discover qBitrr
• 💰 Sponsor: Patreon | ***

📄 License

Released under the https://github.com/Feramance/qBitrr/blob/master/LICENSE. Use it, modify it, share it—commercially or personally.

Star History