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
-
Configure qBittorrent in your config file (Docker:
/config/config.toml; native:.config/config.tomlin the current directory, or path set byQBITRR_OVERRIDES_DATA_PATH):[qBit] Host = "localhost" Port = 8080 UserName = "admin" Password = "adminpass"
-
Add Arr instances:
[Radarr-Movies] URI = "http://localhost:7878" APIKey = "your-radarr-api-key" Category = "radarr-movies"
-
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:
📄 License
Released under the MIT License. Use it, modify it, share it—commercially or personally.
Star History
Made with ❤️ by the qBitrr community
Documentation • PyPI • Docker • GitHub
1 maintainer
Metadata
1 maintainer
Release files for qBitrr2 5.14.5.post3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| qbitrr2-5.14.5.post3.tar.gz | 1.2 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| qbitrr2-5.14.5.post3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.3 MB
Release files / qbitrr2-5.14.5.post3.tar.gz
| Download URL | qbitrr2-5.14.5.post3.tar.gz |
|---|---|
| Size | 1.2 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
612ad631a83c5999c1dc4b55de5dfcf7893c3ba61cf89a2bfafa15495676163e
|
|
BLAKE2b-256 checksum How to use checksums |
f5df2754edafb894ddb2a7f6dcaa6722f9e4e0f308845fafef928c8effcd0bc6
|
| 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 Oct 5, 2026.
Transparency logRelease files / qbitrr2-5.14.5.post3-py3-none-any.whl
| Download URL | qbitrr2-5.14.5.post3-py3-none-any.whl |
|---|---|
| Size | 1.1 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f6d99e22a24c768a1ee57907e885ba4e29c73c790df8e8c8b4c81d050a9c9a89
|
|
BLAKE2b-256 checksum How to use checksums |
215f5545acc46a942bcf11860f0d861b02c03118741472625da74dab2347584f
|
| 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 Oct 5, 2026.
Transparency log
