qBitrr

Torrentarr – Companion tools and automation for the *Arr ecosystem.

🧩 The intelligent glue between qBittorrent and the *Arr ecosystem (Radarr, Sonarr, Lidarr, Readarr). 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/

• Getting Started – Installation guides for pip, Docker, and native setups
• Configuration – qBittorrent, Arr instances, quality profiles, and more
• Features – Health monitoring, automated search, quality management, disk space, auto-updates
• WebUI – Built-in React dashboard with live monitoring and config editor
• Troubleshooting – Common issues and debug logging
• API Reference – REST API documentation

⚡ Quick Start

🐍 Install with pip

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

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

Docker Compose:

services:
  qbitrr:
    image: feramance/qbitrr:stable
    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.

Use :stable for production (feature/fix releases). :latest also includes weekly dependency builds; :nightly tracks master. See the Docker installation guide for details.

✨ Key Features

• 🚀 Multi-qBittorrent Support – Manage torrents across multiple qBittorrent instances for load balancing, redundancy, and VPN 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):

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

2. Add Arr instances:

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

3. Set completed folder:

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

Multi-qBittorrent

Manage torrents across multiple qBittorrent instances:

[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 (multi-instance section) for complete documentation.

See Configuration Guide and config.example.toml for all available options.

📖 Resources

• PyPI Package: https://pypi.org/project/qBitrr2/
• Docker Hub: https://hub.docker.com/r/feramance/qbitrr
• Example Config: config.example.toml
• Systemd Setup: docs/getting-started/installation/systemd.md

🐛 Issues & Support

• Report Bugs: Bug Report Template
• Request Features: Feature Request Template
• Discussions: GitHub Discussions
• Troubleshooting: Common Issues

🤝 Contributing

Contributions welcome! See docs/development/contributing.md for coding guidelines and development setup.

Development setup:

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

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

🤖 AI Assistance

AI tools are used to help keep up with project maintenance—implementation assistance, reviewing large surfaces, and docs/CI churn. All project decisions, and all code and documentation changes, are made and manually reviewed by the maintainer before they land. AI is a tool, not an autonomous maintainer; accountability for this repository remains with the human maintainer(s).

❤️ Support

If qBitrr saves you time and headaches:

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

📄 License

Released under the MIT License. Use it, modify it, share it—commercially or personally.

Star History