Skip to content

README.md

Latest commit

 

History

History
191 lines (147 loc) · 7.72 KB

README.md

File metadata and controls

191 lines (147 loc) · 7.72 KB

qBitrr Logo qBitrr

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

PyPI Downloads Docker Pulls CodeQL Nightly Build pre-commit.ci License: MIT

🧩 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/

  • 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:latest

Docker Compose:

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 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 (v5.7.x+)

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

🐛 Issues & Support

🤝 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

❤️ 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.

Made with ❤️ by the qBitrr community

Documentation • PyPI • Docker • GitHub

Star History

Star History Chart