feramance/qbitrr repository overview

⁠ qBitrr

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

⁠📚 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"
   

   Copy

2. Add Arr instances:

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

   Copy

3. Set completed folder:

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

   Copy

⁠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

⁠