Skip to main content

qBitrr Logo qBitrr

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

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

🧩 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

🐛 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

🤖 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

Star History Chart

Made with ❤️ by the qBitrr community

Documentation • PyPI • Docker • GitHub

Metadata

Release files for qBitrr2 5.14.4.post1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qBitrr2 5.14.4.post1
File Size Uploaded Provenance Actions
qbitrr2-5.14.4.post1.tar.gz 1.2 MB With provenance Details for qbitrr2-5.14.4.post1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qBitrr2 5.14.4.post1
File Interpreter ABI Platform Actions
qbitrr2-5.14.4.post1-py3-none-any.whl Python 3 none any Details for qbitrr2-5.14.4.post1-py3-none-any.whl

Total release size: 2.3 MB

Release files / qbitrr2-5.14.4.post1.tar.gz

Download URL qbitrr2-5.14.4.post1.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
55e54962cf40cf1a016c3596ae16f63f63b8517e08f4ab412e78a3d2c10f1028
BLAKE2b-256 checksum
How to use checksums
2b0c32d95cb4574df838e4a664531630bb61007a8e0b2b5d6a2f2b75fa499216
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 19, 2026.

Transparency log

Release files / qbitrr2-5.14.4.post1-py3-none-any.whl

Download URL qbitrr2-5.14.4.post1-py3-none-any.whl
Size 1.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
c8aae079e7e57f0ff43b776c137dcbbc2b191531f14a4b67bb6ee9d3b3766e8a
BLAKE2b-256 checksum
How to use checksums
1e28286b0a791937551afa568c131d004c12f0a4a35c0877e16b04b64a9d0162
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 19, 2026.

Transparency log

Security for qBitrr2 5.14.4.post1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for qbitrr2-5.14.4.post1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page