# qBitrr
[](https://pypi.org/project/qBitrr2/)
[](https://pypi.org/project/qBitrr2/)
[](https://hub.docker.com/r/feramance/qbitrr)
[](https://github.com/Feramance/qBitrr/actions/workflows/codeql.yml)
[](https://github.com/Feramance/qBitrr/actions/workflows/nightly.yml)
[](https://results.pre-commit.ci/latest/github/Feramance/qBitrr/master)
[](LICENSE)
> 🧩 qBitrr keeps qBittorrent, Radarr, Sonarr, Lidarr, and your request tools chatting happily so downloads finish, import, and clean up without babysitting.
## 📚 What's Inside
- [Overview](#-overview)
- [Core Features](#-core-features)
- [State of the Project](#-state-of-the-project)
- [Quickstart](#-quickstart)
- [Install with pip](#install-with-pip)
- [Run with Docker](#run-with-docker)
- [Native Systemd Service](#native-systemd-service)
- [Configuration](#-configuration)
- [Feature Deep Dive](#-feature-deep-dive)
- [Torrent Health Monitoring](#-torrent-health-monitoring)
- [Automated Search & Requests](#-automated-search--requests)
- [Quality Management](#-quality-management)
- [Seeding & Tracker Control](#-seeding--tracker-control)
- [Disk Space Management](#-disk-space-management)
- [Auto-Updates & Restarts](#-auto-updates--restarts)
- [Built-in Web UI](#-built-in-web-ui)
- [Day-to-day Operations](#-day-to-day-operations)
- [Troubleshooting](#-troubleshooting)
- [Contributing](#-contributing)
- [Support](#-support)
- [License](#-license)
## 🧠 Overview
qBitrr is the intelligent glue between qBittorrent and the *Arr ecosystem (Radarr, Sonarr, Lidarr). It monitors torrent health, triggers instant imports when downloads complete, automates quality upgrades, manages disk space, integrates with request systems (Overseerr/Ombi), and provides a modern React dashboard for complete visibility and control.
## ✨ Core Features
### 🚑 Torrent Health & Import Management
- **Instant imports** – trigger `DownloadedMoviesScan`/`DownloadedEpisodesScan` the moment torrents finish
- **Stalled torrent detection** – identify and handle stuck/slow downloads with configurable thresholds
- **Failed download handling** – automatically blacklist failed torrents in Arr instances and trigger re-searches
- **FFprobe verification** – validate media files are playable before import (auto-downloads FFprobe binary)
- **Smart file filtering** – exclude samples, extras, trailers via regex and extension allowlists
### 🔍 Automated Search & Request Integration
- **Missing media search** – automatically search for missing movies/episodes/albums on schedules
- **Quality upgrade search** – find better releases for existing media based on quality profiles
- **Custom format scoring** – search for releases meeting minimum custom format scores
- **Overseerr/Ombi integration** – auto-pull and prioritize user requests from request management tools
- **Smart search modes** – series-level or episode-level search for TV shows based on context
- **Temporary quality profiles** – use lower quality profiles for missing items, upgrade later
### 📊 Quality & Metadata Management
- **RSS sync automation** – schedule periodic RSS feed refreshes across all Arr instances
- **Queue management** – auto-refresh download queues to keep Arr instances in sync
- **Custom format enforcement** – automatically remove torrents not meeting minimum CF scores
- **Quality profile switching** – dynamically change profiles for missing vs. upgrade searches
- **Year-based search ordering** – prioritize searches by release date (newest first or reverse)
### 🌱 Seeding & Tracker Control
- **Per-tracker settings** – configure MaxETA, ratios, seeding time per tracker
- **Global seeding limits** – set upload/download rate limits, max ratios, and seeding times
- **Automatic removal** – remove torrents based on ratio, time, or both
- **Dead tracker cleanup** – auto-remove trackers with specific error messages
- **Tracker injection** – add missing trackers or remove existing ones per torrent
- **Super seed mode** – enable super seeding for specific trackers
- **Tag management** – auto-tag torrents by tracker or custom rules
### 💾 Disk Space & Resource Management
- **Free space monitoring** – pause all torrents when disk space falls below threshold
- **Auto pause/resume** – intelligently manage torrent activity based on disk availability
- **Configurable thresholds** – set limits in KB, MB, GB, or TB
- **Path-specific monitoring** – watch specific directories for space issues
### 🔄 Auto-Updates & Self-Healing
- **GitHub release-based updates** – automatically checks for published (non-draft) releases via GitHub API
- **Scheduled auto-updates** – update qBitrr on a cron schedule (default: weekly Sunday 3 AM)
- **Manual update trigger** – one-click updates from WebUI
- **Installation-aware updates** – detects git/pip/binary installs and uses appropriate update method
- **Version verification** – confirms installed version matches target before restart
- **Smart restart mechanism** – uses `os.execv()` for true in-place restarts (no supervisor needed)
- **Cross-platform compatibility** – works in Docker, systemd, native installs, Windows, Linux, macOS
- **Graceful shutdown** – cleanly closes databases, flushes logs, terminates child processes
### 💻 First-Party Web UI
- **Live process monitoring** – see all running Arr managers and their current activity
- **Log viewer** – tail logs in real-time with filtering and search
- **Arr insights** – view movies, series, albums with filtering by year, quality, status
- **Config editor** – edit configuration directly from the UI
- **Restart controls** – restart individual processes or the entire application
- **Dark/light theme** – customizable UI appearance
- **Token authentication** – optional API protection with bearer tokens
## 📌 State of the Project
The long-term plan is still to ship a C# rewrite, but the Python edition isn't going anywhere—it gets regular fixes and features, and the Web UI is now production-ready. Ideas and PRs are welcome! Head over to the [issue templates](.github/ISSUE_TEMPLATE) or the [PR checklist](.github/pull_request_template.md) to get started.
## ⚡ Quickstart
qBitrr supports Python 3.12+ on Linux, macOS, and Windows. Run it natively or in Docker—whatever fits your stack.
### 🐍 Install with pip
```bash
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install qBitrr2
# First run creates ~/config/config.toml
qBitrr2
```
**Update later:**
```bash
python -m pip install --upgrade qBitrr2
```
**Or enable auto-updates** in `config.toml`:
```toml
[Settings]
AutoUpdateEnabled = true
AutoUpdateCron = "0 3 * * 0" # Weekly on Sunday at 3 AM
```
> 📝 **Note:** Auto-updates check GitHub releases for new versions. Only published (non-draft) releases trigger updates. Binary installations receive update notifications but require manual download.
### 🐳 Run with Docker
**Minimal setup:**
```bash
docker run -d \
--name qbitrr \
--tty \
-e TZ=Europe/London \
-p 6969:6969 \
-v /etc/localtime:/etc/localtime:ro \
-v /path/to/appdata/qbitrr:/config \
-v /path/to/completed/downloads:/completed_downloads:rw \
--restart unless-stopped \
feramance/qbitrr:latest
```
The container automatically binds its WebUI to `0.0.0.0`; exposing `6969` makes the dashboard reachable at `http://<host>:6969/ui`.
**Docker Compose example:**
```yaml
services:
qbitrr:
image: feramance/qbitrr:latest
container_name: qbitrr
user: 1000:1000
restart: unless-stopped
tty: true
environment:
TZ: Europe/London
ports:
- "6969:6969"
volumes:
- /etc/localtime:/etc/localtime:ro
- /path/to/appdata/qbitrr:/config
- /path/to/completed/downloads:/completed_downloads:rw
logging:
driver: json-file
options:
max-size: 50m
max-file: "3"
depends_on:
- qbittorrent
- radarr
- sonarr
```
> ℹ️ On first boot the container writes `config.toml` under `/config`. Update the values to match your mounts and restart the container.
### ⚙️ Native Systemd Service
For Linux users running qBitrr natively (non-Docker), you can set up automatic startup and restart management using systemd.
**Quick setup:**
```bash
# Install qBitrr
pip install qBitrr2
# Copy systemd service file
sudo cp qbitrr.service /etc/systemd/system/qbitrr.service
# Enable and start
sudo systemctl enable qbitrr
sudo systemctl start qbitrr
# Check status
sudo systemctl status qbitrr
```
**Benefits:**
- ✅ Auto-start on boot
- ✅ Automatic restarts after crashes or updates
- ✅ Integrated logging with `journalctl`
- ✅ Resource limits and security hardening
- ✅ Works seamlessly with qBitrr's auto-update feature
**See the full guide:** [SYSTEMD_SERVICE.md](SYSTEMD_SERVICE.md) for detailed setup instructions, troubleshooting, and security hardening options.
## 🛠️ Configuration
### 📂 Config Location
- **Native install:** `~/config/config.toml`
- **Docker:** `/config/config.toml`
- **First run:** Auto-generates a template config file
- **Manual generation:** `qbitrr --gen-config`
### 🔧 Essential Setup
1. **Configure qBittorrent connection** in `[qBit]` section:
- Set `Host`, `Port`, `UserName`, `Password`
- qBittorrent 5.x requires `Version5 = true` (4.6.7 is the latest validated 4.x build)
2. **Configure Arr instances** (Radarr/Sonarr/Lidarr):
- Each instance needs: `URI`, `APIKey`, `Category`
- **Important:** Use matching categories in Arr's download client settings
- **Tagging:** Ensure Arr instances tag their downloads so qBitrr can track them
3. **Set completed download folder:**
```toml
[Settings]
CompletedDownloadFolder = "/path/to/completed"
```
4. **Enable logging** for troubleshooting:
```toml
[Settings]
Logging = true
ConsoleLevel = "INFO" # or DEBUG for verbose output
```
### 📖 Configuration Reference
See [`config.example.toml`](config.example.toml) for comprehensive documentation of all settings, including:
- Torrent health check thresholds
- Search automation options
- Seeding limits and tracker rules
- Request system integration
- WebUI settings
- File filtering and exclusion rules
## 🎯 Feature Deep Dive
### 🚑 Torrent Health Monitoring
qBitrr continuously monitors your torrents and takes intelligent action when problems arise.
**Stalled Torrent Detection:**
```toml
[Radarr-Movies.Torrent]
StalledDelay = 15 # Minutes before considering a torrent stalled
ReSearchStalled = true # Re-search before removing stalled torrents
MaximumETA = 604800 # Max ETA in seconds (7 days)
IgnoreTorrentsYoungerThan = 600 # Grace period for new torrents (10 min)
```
**Automatic Blacklisting:**
When torrents fail or stall beyond thresholds, qBitrr:
1. ✅ Marks the release as failed in the Arr instance
2. ✅ Blacklists the release to prevent re-download
3. ✅ Optionally triggers an automatic re-search
4. ✅ Removes the failed torrent from qBittorrent
**Smart Completion Rules:**
```toml
[Radarr-Movies.Torrent]
MaximumDeletablePercentage = 0.99 # Don't delete torrents >99% complete
DoNotRemoveSlow = true # Protect slow but active torrents
```
**File Verification:**
```toml
[Settings]
FFprobeAutoUpdate = true # Auto-download FFprobe binary
```
- Validates media files are playable before import
- Detects corrupted or fake files
- Prevents broken media from being imported into Arr
**Error Code Handling:**
```toml
[Radarr-Movies]
ArrErrorCodesToBlocklist = [
"Not an upgrade for existing movie file(s)",
"Unable to determine if file is a sample"
]
```
Automatically handle specific Arr error messages by removing failed files and triggering re-searches.
---
### 🔍 Automated Search & Requests
**Missing Media Search:**
```toml
[Radarr-Movies.EntrySearch]
SearchMissing = true # Enable automated searching
SearchLimit = 5 # Max concurrent searches
SearchByYear = true # Order by release year
SearchInReverse = false # Newest first (true = oldest first)
SearchRequestsEvery = 300 # Delay between searches (seconds)
SearchAgainOnSearchCompletion = true # Loop continuously
```
**Quality Upgrade Search:**
```toml
[Radarr-Movies.EntrySearch]
DoUpgradeSearch = true # Search for better quality versions
QualityUnmetSearch = true # Search for unmet quality profiles
CustomFormatUnmetSearch = true # Search for better custom format scores
ForceMinimumCustomFormat = true # Auto-remove torrents below CF threshold
```
**Overseerr Integration:**
```toml
[Radarr-Movies.EntrySearch.Overseerr]
SearchOverseerrRequests = true
OverseerrURI = "http://overseerr:5055"
OverseerrAPIKey = "your-api-key"
ApprovedOnly = true # Only process approved requests
Is4K = false # Set true for 4K Arr instances
```
**Ombi Integration:**
```toml
[Radarr-Movies.EntrySearch.Ombi]
SearchOmbiRequests = true
OmbiURI = "http://ombi:3579"
OmbiAPIKey = "your-api-key"
ApprovedOnly = true
```
**Smart Search Modes (Sonarr):**
```toml
[Sonarr-TV.EntrySearch]
SearchBySeries = "smart" # auto | true (series) | false (episode)
# smart: Series search for full seasons, episode search for singles
PrioritizeTodaysReleases = true # Search today's episodes first (RSS-like)
AlsoSearchSpecials = false # Include season 00 episodes
Unmonitored = false # Include unmonitored items
```
**Temporary Quality Profiles:**
```toml
[Radarr-Movies.EntrySearch]
UseTempForMissing = true
KeepTempProfile = false
MainQualityProfile = ["Ultra-HD", "HD-1080p"]
TempQualityProfile = ["Web-DL", "HDTV-720p"]
# Searches missing items with temp profile, switches back after import
```
---
### 📊 Quality Management
**RSS Sync Automation:**
```toml
[Radarr-Movies]
RssSyncTimer = 5 # Minutes between RSS feed refreshes (0 = disabled)
```
Keeps Arr instances checking indexers for new releases regularly.
**Queue Refresh:**
```toml
[Radarr-Movies]
RefreshDownloadsTimer = 5 # Minutes between queue updates (0 = disabled)
```
Ensures Arr instances stay in sync with qBittorrent's download state.
**Import Mode:**
```toml
[Radarr-Movies]
importMode = "Auto" # Auto | Move | Copy
```
- **Auto:** Let Arr decide based on its settings
- **Move:** Move files from download folder to library
- **Copy:** Copy files (preserves seeding torrents)
**Custom Format Score Enforcement:**
When `ForceMinimumCustomFormat = true`, qBitrr automatically removes torrents that don't meet the minimum custom format score defined in your Arr quality profile.
---
### 🌱 Seeding & Tracker Control
**Global Seeding Limits:**
```toml
[Radarr-Movies.Torrent.SeedingMode]
DownloadRateLimitPerTorrent = -1 # -1 = unlimited, or KB/s
UploadRateLimitPerTorrent = -1 # -1 = unlimited, or KB/s
MaxUploadRatio = 2.0 # Stop seeding at 2.0 ratio
MaxSeedingTime = 604800 # Stop after 7 days (seconds)
RemoveTorrent = 3 # 1=ratio, 2=time, 3=either, 4=both, -1=never
```
**Per-Tracker Settings:**
```toml
[[Radarr-Movies.Torrent.Trackers]]
Name = "MyTracker"
Priority = 10 # Higher = processed first
URI = "https://tracker.example/announce"
MaximumETA = 18000 # Override global MaxETA for this tracker
DownloadRateLimit = 5000 # KB/s limit for this tracker
UploadRateLimit = 1000 # KB/s limit for this tracker
MaxUploadRatio = 1.5 # Tracker-specific ratio limit
MaxSeedingTime = 86400 # Tracker-specific time limit (1 day)
AddTrackerIfMissing = true # Inject this tracker into matching torrents
RemoveIfExists = false # Remove this tracker if found
SuperSeedMode = true # Enable super seeding for this tracker
AddTags = ["private", "MyTracker"] # Auto-tag matching torrents
```
**Tracker Cleanup:**
```toml
[Radarr-Movies.Torrent.SeedingMode]
RemoveDeadTrackers = true
RemoveTrackerWithMessage = [
"skipping tracker announce (unreachable)",
"No such host is known",
"unsupported URL protocol"
]
```
**File Filtering:**
```toml
[Radarr-Movies.Torrent]
CaseSensitiveMatches = false
FolderExclusionRegex = ["\\bextras?\\b", "\\bsamples?\\b", "\\bfeaturettes?\\b"]
FileNameExclusionRegex = ["\\bsample\\b", "\\btrailer\\b"]
FileExtensionAllowlist = [".mp4", ".mkv", ".avi", ".sub", ".srt"]
AutoDelete = false # Auto-delete non-playable files (.exe, .png, etc.)
```
---
### 💾 Disk Space Management
**Free Space Monitoring:**
```toml
[Settings]
FreeSpace = "50G" # Pause when <50GB free (K/M/G/T units)
FreeSpaceFolder = "/downloads" # Path to monitor
AutoPauseResume = true # Required for FreeSpace to work
```
**How it works:**
1. 📊 Continuously monitors specified folder
2. ⏸️ Pauses **all** torrents when space falls below threshold
3. ▶️ Auto-resumes when space is reclaimed
4. 🔔 Logs warnings when approaching limit
**Disable monitoring:**
```toml
[Settings]
### 🔄 Auto-Updates & Restarts
qBitrr can automatically update itself by checking GitHub releases for new versions. The update behavior varies by installation type.
#### 🔍 How Updates Work
**Update Detection:**
1. 📡 Queries GitHub API for latest **published** (non-draft) release
2. 🔢 Compares release version with current version using semantic versioning
3. ⏩ Skips prereleases (beta, rc, alpha) by default
4. 📦 Only updates when a newer **stable** version is available
**Installation Types:**
| Type | Detection | Update Method | Version Control |
|------|-----------|---------------|-----------------|
| **Git** | `.git` directory exists | `git checkout <tag>` or `git pull` | Checks out specific release tag |
| **PyPI** | Installed via pip | `pip install qBitrr2==<version>` | Installs exact version from PyPI |
| **Binary** | PyInstaller executable | Notification only | Logs download URL for manual update |
**Why different methods?**
- **Git installations** can checkout specific tags for precise version control
- **PyPI installations** can pin to exact versions for reliability
- **Binary installations** cannot self-update (would require replacing running executable), so qBitrr logs the download URL and version info for manual update
---
#### ⚙️ Configuration
**Basic Setup:**
```toml
[Settings]
AutoUpdateEnabled = true
AutoUpdateCron = "0 3 * * 0" # Cron expression (default: Sunday 3 AM)
```
**Cron Expression Examples:**
```toml
"0 3 * * 0" # Every Sunday at 3:00 AM
"0 */6 * * *" # Every 6 hours
"0 0 * * *" # Daily at midnight
"0 2 * * 1-5" # Weekdays at 2:00 AM
```
---
#### 📋 Update Process Flow
**For Git & PyPI Installations:**
1. **Check Phase:**
- Fetch latest release from GitHub API
- Validate release is not draft or prerelease
- Compare versions (semantic versioning)
- Skip if already on latest version
2. **Download Phase:**
- **Git:** `git fetch --tags && git checkout v<version>`
- **PyPI:** `pip install --upgrade qBitrr2==<version>`
3. **Verification Phase:**
- Reload version information
- Verify installed version matches target
- Log warning if mismatch
4. **Restart Phase:**
- Gracefully shutdown (close DBs, flush logs)
- Terminate child processes
- Execute in-place restart via `os.execv()`
- Maintain same PID (systemd-friendly)
**For Binary Installations:**
1. **Check Phase:** Same as above
2. **Notification:** Logs message with download URL and instructions
3. **Manual Update:** User downloads new binary from GitHub releases
4. **No Auto-Restart:** User manually restarts after replacing binary
Example binary update log:
```
[INFO] Update available: v5.4.2 -> v5.4.3
[INFO] Binary installation detected - manual update required
[INFO] Download: https://github.com/Feramance/qBitrr/releases/latest
[INFO] Instructions:
1. Download the binary for your platform
2. Extract the archive
3. Replace current executable with new binary
4. Restart qBitrr
```
---
#### 🔧 Manual Updates
**Via WebUI:**
- Navigate to **Config tab**
- Click **"Check for Updates"** to see available version
- Click **"Update Now"** button
- Confirm when prompted
- Application restarts automatically (git/pip only)
**Via Command Line:**
```bash
# Git installation
cd /path/to/qBitrr
git fetch --tags
git checkout v5.4.3 # or: git pull
qbitrr # restart
# PyPI installation
pip install --upgrade qBitrr2
# or: pip install qBitrr2==5.4.3 # specific version
qbitrr # restart
# Binary installation
# Download from: https://github.com/Feramance/qBitrr/releases/latest
# Extract and replace binary, then restart
# Docker installation
docker pull feramance/qbitrr:latest
docker restart qbitrr
# or: docker-compose pull && docker-compose up -d
```
---
#### 🔐 Security & Reliability
**GitHub API Dependency:**
- Auto-update requires GitHub API access
- Rate limit: 60 requests/hour (unauthenticated)
- Cron schedule should account for rate limits
- Failures are logged but don't crash the application
**Version Verification:**
- After update, qBitrr verifies installed version
- Helps catch failed updates or PyPI lag issues
- Logs warning if version mismatch detected
**Draft & Prerelease Handling:**
- Draft releases are **always skipped** (unpublished)
- Prereleases (beta/rc/alpha) are skipped by default
- Useful for testing but not recommended for production
**Rollback:**
- Git installations: `git checkout <previous-tag>`
- PyPI installations: `pip install qBitrr2==<previous-version>`
- Binary installations: Keep backup of previous binary
- No automatic rollback (manual intervention required)
---
#### 🚀 Restart Mechanism
**How it Works:**
```python
os.execv(sys.executable, [sys.executable] + sys.argv)
```
**Benefits:**
- ✅ **Same PID** – systemd doesn't detect a restart
- ✅ **No supervisor** – doesn't require external process manager
- ✅ **Clean state** – fresh Python interpreter, no memory leaks
- ✅ **Fast** – near-instant restart (< 1 second)
**Supported Environments:**
- 🐳 **Docker** – container stays running, process restarts
- ⚙️ **systemd** – service remains "active", no restart count increment
- 💻 **Native** – works on Linux, macOS, Windows
- 🪟 **Windows** – handles different executable extensions (.exe, .cmd)
**Graceful Shutdown:**
1. Stop all Arr manager child processes
2. Close database connections
3. Flush log buffers to disk
4. Release file locks
5. Execute in-place restart
---
#### 🛠️ Restart via API
**Restart entire application:**
```bash
curl -X POST http://localhost:6969/api/restart
# With authentication
curl -X POST http://localhost:6969/api/restart \
-H "Authorization: Bearer your-token"
```
**Restart specific Arr manager:**
```bash
curl -X POST http://localhost:6969/api/arr/radarr-movies/restart
```
---
#### ⚠️ Troubleshooting Updates
**Update not triggering:**
- ✅ Check `AutoUpdateEnabled = true` in config
- ✅ Verify cron expression is valid (use [crontab.guru](https://crontab.guru))
- ✅ Check `Main.log` for GitHub API errors
- ✅ Ensure internet connectivity to api.github.com
- ✅ Check if already on latest version
**Version mismatch after update:**
- ✅ Review logs for pip/git errors
- ✅ Manually verify installation: `pip show qBitrr2` or `git describe`
- ✅ Check if PyPI is behind GitHub releases (can take hours)
- ✅ Try manual update to force correct version
**Binary updates not working:**
- ℹ️ **Expected behavior** – binaries cannot auto-update
- ✅ Check logs for download URL
- ✅ Download matching binary for your platform
- ✅ Extract and replace current executable
- ✅ Ensure new binary has execute permissions (Unix)
**Restart fails:**
- ✅ Check file permissions on qBitrr installation
- ✅ Review systemd journal if using systemd
- ✅ Verify no file locks preventing restart
- ✅ Check disk space for logs and databases
- ✅ Manual restart: Stop service, start again
**For systemd users:** See [SYSTEMD_SERVICE.md](SYSTEMD_SERVICE.md) for automatic restart configuration with `Restart=always`.
---
curl -X POST http://localhost:6969/api/arr/radarr-movies/restart
```
**For systemd users:** See [SYSTEMD_SERVICE.md](SYSTEMD_SERVICE.md) for automatic restart configuration.
---
## 🖥️ Built-in Web UI
The React + Vite dashboard provides complete visibility and control over your qBitrr instance.
### 🌐 Access & Authentication
- **Default URL:** `http://<host>:6969/ui`
- **Custom host/port:** Configure in `config.toml`:
```toml
[WebUI]
Host = "0.0.0.0" # Bind address (0.0.0.0 for all interfaces)
Port = 6969 # Web server port
```
- **Authentication:** Protect API endpoints with bearer token:
```toml
[WebUI]
Token = "your-secret-token"
```
When set, all `/api/*` endpoints require `Authorization: Bearer <token>` header.
The UI itself uses unauthenticated `/web/*` endpoints.
### 🗂️ Dashboard Tabs
**📊 Processes Tab:**
- View all running Arr manager processes
- See current activity and search status
- Monitor queue counts and metrics
- Restart individual processes or all at once
**📝 Logs Tab:**
- Real-time log viewer with filtering
- View `Main.log`, `WebUI.log`, and per-Arr logs
- Search and navigate large log files
- Download logs for troubleshooting
**🎬 Radarr/Sonarr/Lidarr Tabs:**
- Browse your media library with advanced filtering
- Filter by year range, quality status, monitored state
- See custom format scores and upgrade availability
- Identify missing media and quality issues
- View request status for Overseerr/Ombi items
**⚙️ Config Tab:**
- Edit configuration directly in the UI
- Trigger manual updates
- View version and changelog
- Rebuild Arr metadata
- Restart application
### 🎨 Customization
```toml
[WebUI]
Theme = "dark" # or "light"
LiveArr = true # Enable live updates for Arr views
GroupSonarr = true # Group episodes by series
GroupLidarr = true # Group albums by artist
```
### 🧪 Development
The WebUI source lives in `webui/`:
```bash
cd webui
npm ci # Install dependencies
npm run dev # Dev server with HMR at localhost:5173
npm run lint # ESLint check
npm run build # Build for production
```
Build outputs to `webui/dist/`, which gets bundled into `qBitrr/static/`.
**API Documentation:** See [API_DOCUMENTATION.md](API_DOCUMENTATION.md) for complete API reference.
---
## 🔁 Day-to-day Operations
### 🔄 Restart & Rebuild
- **Restart application:** WebUI → Config tab → "Restart All" button
- **Restart individual Arr manager:** WebUI → Processes tab → Click restart icon
- **Rebuild Arr metadata:** WebUI → Config tab → "Rebuild Arrs" button
- **API endpoints:**
```bash
POST /api/restart # Restart qBitrr
POST /api/arr/<category>/restart # Restart specific manager
POST /api/arr/rebuild # Rebuild all Arr caches
```
### 📋 Monitoring
- **Logs location:** `~/logs/` (native) or `/config/logs` (Docker)
- **Log files:**
- `Main.log` – Main application logs
- `WebUI.log` – Web interface logs
- `<CategoryName>.log` – Per-Arr instance logs
- **View in UI:** WebUI → Logs tab → Select log file
- **View in terminal:**
```bash
# Native
tail -f ~/logs/Main.log
# Docker
docker logs -f qbitrr
docker exec qbitrr tail -f /config/logs/Main.log
# Systemd
sudo journalctl -u qbitrr -f
```
### 🔍 Request Integration
Once configured, qBitrr automatically:
1. 📥 Polls Overseerr/Ombi for new requests
2. 🔍 Searches requested items in Arr instances
3. ⭐ Prioritizes requests over general missing media searches
4. 📊 Identifies requests in WebUI Arr tabs with `isRequest` flag
### 🛠️ Special Categories
qBitrr monitors special qBittorrent categories for manual intervention:
**Failed Category:**
```toml
[Settings]
FailedCategory = "failed"
```
Manually move torrents here to mark them as failed and trigger blacklisting + re-search.
**Recheck Category:**
```toml
[Settings]
RecheckCategory = "recheck"
```
Manually move torrents here to trigger a proper recheck operation.
### 🏷️ Tagless Operation
```toml
[Settings]
Tagless = true
```
Run qBitrr without requiring Arr instances to tag their torrents. Less precise but works without Arr configuration changes.
---
## 🆘 Troubleshooting
### 🐛 Common Issues
**Torrents not being processed:**
1. ✅ Verify Arr instance is using the correct **category** in download client settings
2. ✅ Ensure Arr instance **tags** match qBitrr's category configuration
3. ✅ Check `IgnoreTorrentsYoungerThan` – new torrents have a grace period
4. ✅ Enable debug logging: `ConsoleLevel = "DEBUG"`
5. ✅ Check category-specific log file in `~/logs/` or `/config/logs/`
**Imports not triggering:**
1. ✅ Verify `CompletedDownloadFolder` path is correct and accessible
2. ✅ Check file extensions against `FileExtensionAllowlist`
3. ✅ Review `FolderExclusionRegex` and `FileNameExclusionRegex` for over-matching
4. ✅ Enable FFprobe logging to see media validation results
5. ✅ Check Arr instance has proper path mappings (especially in Docker)
**Search not finding releases:**
1. ✅ Verify `SearchMissing = true` in the EntrySearch section
2. ✅ Check `SearchLimit` isn't too low for your queue
3. ✅ Review `SearchByYear` and `SearchInReverse` settings
4. ✅ Ensure Arr instance has indexers configured and working
5. ✅ Check for rate limiting in Arr instance logs
**High CPU/memory usage:**
1. ✅ Reduce `SearchLimit` to lower concurrent searches
2. ✅ Increase `LoopSleepTimer` to slow down processing
3. ✅ Disable `DoUpgradeSearch` if not needed
4. ✅ Set `LiveArr = false` in WebUI config to reduce refresh overhead
**Docker path issues:**
1. ✅ Ensure volume mounts match between qBittorrent, Arr, and qBitrr
2. ✅ Use consistent paths across all containers
3. ✅ Example: All containers should see `/downloads` as the same physical path
**Updates failing:**
1. ✅ Check internet connectivity
2. ✅ Verify pip/Python installation is writable
3. ✅ Review update logs in `Main.log` or `WebUI.log`
4. ✅ Manual update: `pip install --upgrade qBitrr2` (native) or pull new Docker image
### 📊 Enable Debug Logging
```toml
[Settings]
Logging = true
ConsoleLevel = "DEBUG" # TRACE for even more detail
```
Logs output to:
- **Native:** `~/logs/`
- **Docker:** `/config/logs/`
- **Systemd:** `sudo journalctl -u qbitrr -n 100`
### 🐞 Reporting Issues
When reporting bugs:
1. **Enable file logging** and reproduce the issue
2. **Collect information:**
- qBitrr version: `qBitrr2 --version` or Docker tag
- OS and deployment method (Docker/native/systemd)
- qBittorrent version and API version (4.x vs 5.x)
- Arr instance versions (Radarr/Sonarr/Lidarr)
- Request tool versions (Overseerr/Ombi) if applicable
3. **Grab relevant log snippets** (scrub API keys and tokens!)
4. **Open an issue** using the [bug report template](.github/ISSUE_TEMPLATE/bug_report.yml)
5. **Include:**
- Clear reproduction steps
- Expected vs. actual behavior
- Relevant config sections (with secrets removed)
- Error messages and stack traces
### 💡 Feature Requests
Have an idea? Submit it via the [feature request template](.github/ISSUE_TEMPLATE/feature_request.yml)!
### 📚 Additional Resources
- **API Documentation:** [API_DOCUMENTATION.md](API_DOCUMENTATION.md)
- **Systemd Setup:** [SYSTEMD_SERVICE.md](SYSTEMD_SERVICE.md)
- **Example Config:** [config.example.toml](config.example.toml)
- **GitHub Issues:** [Search existing issues](https://github.com/Feramance/qBitrr/issues)
---
## 🤝 Contributing
We welcome contributions from the community! Whether it's code, documentation, bug reports, or feature ideas, your help makes qBitrr better.
### 🔧 Development Setup
**Python Backend:**
```bash
# Clone the repo
git clone https://github.com/Feramance/qBitrr.git
cd qBitrr
# Create virtual environment
make newenv
# or: python -m venv .venv && source .venv/bin/activate
# Install dependencies
make syncenv
# or: pip install -e .[all]
# Run linting and formatting
make reformat
# or: pre-commit run --all-files
```
**TypeScript/React WebUI:**
```bash
cd webui
npm ci # Install exact versions from package-lock.json
npm run dev # Dev server at localhost:5173
npm run lint # ESLint check
npm run build # Build for production
```
### 📝 Before Submitting a PR
1. ✅ Read the [pull request template](.github/pull_request_template.md)
2. ✅ **Format code:**
- Python: `make reformat` or `pre-commit run --all-files`
- TypeScript: `npm run lint` in `webui/`
3. ✅ **Test your changes:**
- Run against live qBittorrent + Arr instances
- Test in both Docker and native environments if possible
4. ✅ **Update documentation:**
- Add/update relevant sections in README.md
- Update `config.example.toml` if adding config options
- Document API changes in `API_DOCUMENTATION.md`
5. ✅ **Clean commit history:**
- Use descriptive commit messages
- Follow [conventional commits](https://www.conventionalcommits.org/) format
- Squash WIP commits before submitting
### 💡 Contribution Ideas
- 🐛 **Bug fixes** – check [open issues](https://github.com/Feramance/qBitrr/issues)
- ✨ **Features** – see [feature requests](https://github.com/Feramance/qBitrr/labels/enhancement)
- 📚 **Documentation** – improve guides, add examples, fix typos
- 🌍 **Translations** – help internationalize the WebUI
- 🧪 **Testing** – add test coverage, validate edge cases
**Unsure if an idea fits?** Open a [feature request](.github/ISSUE_TEMPLATE/feature_request.yml) first and let's discuss!
### 📜 Code Guidelines
See [CONTRIBUTION.md](CONTRIBUTION.md) for comprehensive coding standards and architecture details.
**Quick summary:**
- **Python:** Black formatting (99 chars), type hints required, PEP 8 naming
- **TypeScript:** ESLint strict mode, explicit types, functional components only
- **Commits:** LF line endings, no trailing whitespace, EOF newline required
- **Errors:** Inherit from `qBitManagerError`, provide actionable messages
---
## ❤️ Support
### 🌟 Show Your Support
- ⭐ **Star the repo** – helps others discover qBitrr
- 🐛 **Report bugs** – attach logs so we can fix issues faster
- 💬 **Share feedback** – tell us what works and what doesn't
- 🛠️ **Contribute** – code, docs, translations, or just good vibes
### 💰 Sponsor Development
If qBitrr saves you time and headaches, consider supporting its development:
- 🎨 [Patreon](https://patreon.com/qBitrr) – monthly support
- 💸 [PayPal](https://www.paypal.me/feramance) – one-time donations
Your support keeps qBitrr maintained, updated, and improving. Thank you! 🙏
---
## 📄 License
qBitrr is released under the [MIT License](LICENSE).
**TL;DR:** Use it, modify it, share it—commercially or personally. Just keep the copyright notice and don't blame us if things break. 😊
---
## 🔗 Quick Links
- 📦 [PyPI Package](https://pypi.org/project/qBitrr2/)
- 🐳 [Docker Hub](https://hub.docker.com/r/feramance/qbitrr)
- 📚 [API Documentation](API_DOCUMENTATION.md)
- ⚙️ [Systemd Setup Guide](SYSTEMD_SERVICE.md)
- 📝 [Example Configuration](config.example.toml)
- 🐛 [Report a Bug](.github/ISSUE_TEMPLATE/bug_report.yml)
- ✨ [Request a Feature](.github/ISSUE_TEMPLATE/feature_request.yml)
- 💬 [Discussions](https://github.com/Feramance/qBitrr/discussions)
---
<div align="center">
**Made with ❤️ by the qBitrr community**
</div>
Raw data
{
"_id": null,
"home_page": "https://github.com/Feramance/qBitrr",
"name": "qBitrr2",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.12",
"maintainer_email": null,
"keywords": "qbittorrent, radarr, sonarr, lidarr, arr, automation, torrent, media, plex, jellyfin, overseerr, ombi",
"author": "Feramance",
"author_email": "fera@fera.wtf",
"download_url": "https://files.pythonhosted.org/packages/81/4b/0bb8e3da7c79958e1b28ac1d9a9acf00b005af702b9b47d56a7c44ab9464/qbitrr2-5.4.5.tar.gz",
"platform": null,
"description": "# qBitrr\n\n[](https://pypi.org/project/qBitrr2/)\n[](https://pypi.org/project/qBitrr2/)\n[](https://hub.docker.com/r/feramance/qbitrr)\n[](https://github.com/Feramance/qBitrr/actions/workflows/codeql.yml)\n[](https://github.com/Feramance/qBitrr/actions/workflows/nightly.yml)\n[](https://results.pre-commit.ci/latest/github/Feramance/qBitrr/master)\n[](LICENSE)\n\n> \ud83e\udde9 qBitrr keeps qBittorrent, Radarr, Sonarr, Lidarr, and your request tools chatting happily so downloads finish, import, and clean up without babysitting.\n\n## \ud83d\udcda What's Inside\n- [Overview](#-overview)\n- [Core Features](#-core-features)\n- [State of the Project](#-state-of-the-project)\n- [Quickstart](#-quickstart)\n - [Install with pip](#install-with-pip)\n - [Run with Docker](#run-with-docker)\n - [Native Systemd Service](#native-systemd-service)\n- [Configuration](#-configuration)\n- [Feature Deep Dive](#-feature-deep-dive)\n - [Torrent Health Monitoring](#-torrent-health-monitoring)\n - [Automated Search & Requests](#-automated-search--requests)\n - [Quality Management](#-quality-management)\n - [Seeding & Tracker Control](#-seeding--tracker-control)\n - [Disk Space Management](#-disk-space-management)\n - [Auto-Updates & Restarts](#-auto-updates--restarts)\n- [Built-in Web UI](#-built-in-web-ui)\n- [Day-to-day Operations](#-day-to-day-operations)\n- [Troubleshooting](#-troubleshooting)\n- [Contributing](#-contributing)\n- [Support](#-support)\n- [License](#-license)\n\n## \ud83e\udde0 Overview\nqBitrr is the intelligent glue between qBittorrent and the *Arr ecosystem (Radarr, Sonarr, Lidarr). It monitors torrent health, triggers instant imports when downloads complete, automates quality upgrades, manages disk space, integrates with request systems (Overseerr/Ombi), and provides a modern React dashboard for complete visibility and control.\n\n## \u2728 Core Features\n\n### \ud83d\ude91 Torrent Health & Import Management\n- **Instant imports** \u2013 trigger `DownloadedMoviesScan`/`DownloadedEpisodesScan` the moment torrents finish\n- **Stalled torrent detection** \u2013 identify and handle stuck/slow downloads with configurable thresholds\n- **Failed download handling** \u2013 automatically blacklist failed torrents in Arr instances and trigger re-searches\n- **FFprobe verification** \u2013 validate media files are playable before import (auto-downloads FFprobe binary)\n- **Smart file filtering** \u2013 exclude samples, extras, trailers via regex and extension allowlists\n\n### \ud83d\udd0d Automated Search & Request Integration\n- **Missing media search** \u2013 automatically search for missing movies/episodes/albums on schedules\n- **Quality upgrade search** \u2013 find better releases for existing media based on quality profiles\n- **Custom format scoring** \u2013 search for releases meeting minimum custom format scores\n- **Overseerr/Ombi integration** \u2013 auto-pull and prioritize user requests from request management tools\n- **Smart search modes** \u2013 series-level or episode-level search for TV shows based on context\n- **Temporary quality profiles** \u2013 use lower quality profiles for missing items, upgrade later\n\n### \ud83d\udcca Quality & Metadata Management\n- **RSS sync automation** \u2013 schedule periodic RSS feed refreshes across all Arr instances\n- **Queue management** \u2013 auto-refresh download queues to keep Arr instances in sync\n- **Custom format enforcement** \u2013 automatically remove torrents not meeting minimum CF scores\n- **Quality profile switching** \u2013 dynamically change profiles for missing vs. upgrade searches\n- **Year-based search ordering** \u2013 prioritize searches by release date (newest first or reverse)\n\n### \ud83c\udf31 Seeding & Tracker Control\n- **Per-tracker settings** \u2013 configure MaxETA, ratios, seeding time per tracker\n- **Global seeding limits** \u2013 set upload/download rate limits, max ratios, and seeding times\n- **Automatic removal** \u2013 remove torrents based on ratio, time, or both\n- **Dead tracker cleanup** \u2013 auto-remove trackers with specific error messages\n- **Tracker injection** \u2013 add missing trackers or remove existing ones per torrent\n- **Super seed mode** \u2013 enable super seeding for specific trackers\n- **Tag management** \u2013 auto-tag torrents by tracker or custom rules\n\n### \ud83d\udcbe Disk Space & Resource Management\n- **Free space monitoring** \u2013 pause all torrents when disk space falls below threshold\n- **Auto pause/resume** \u2013 intelligently manage torrent activity based on disk availability\n- **Configurable thresholds** \u2013 set limits in KB, MB, GB, or TB\n- **Path-specific monitoring** \u2013 watch specific directories for space issues\n\n### \ud83d\udd04 Auto-Updates & Self-Healing\n- **GitHub release-based updates** \u2013 automatically checks for published (non-draft) releases via GitHub API\n- **Scheduled auto-updates** \u2013 update qBitrr on a cron schedule (default: weekly Sunday 3 AM)\n- **Manual update trigger** \u2013 one-click updates from WebUI\n- **Installation-aware updates** \u2013 detects git/pip/binary installs and uses appropriate update method\n- **Version verification** \u2013 confirms installed version matches target before restart\n- **Smart restart mechanism** \u2013 uses `os.execv()` for true in-place restarts (no supervisor needed)\n- **Cross-platform compatibility** \u2013 works in Docker, systemd, native installs, Windows, Linux, macOS\n- **Graceful shutdown** \u2013 cleanly closes databases, flushes logs, terminates child processes\n\n### \ud83d\udcbb First-Party Web UI\n- **Live process monitoring** \u2013 see all running Arr managers and their current activity\n- **Log viewer** \u2013 tail logs in real-time with filtering and search\n- **Arr insights** \u2013 view movies, series, albums with filtering by year, quality, status\n- **Config editor** \u2013 edit configuration directly from the UI\n- **Restart controls** \u2013 restart individual processes or the entire application\n- **Dark/light theme** \u2013 customizable UI appearance\n- **Token authentication** \u2013 optional API protection with bearer tokens\n\n## \ud83d\udccc State of the Project\nThe long-term plan is still to ship a C# rewrite, but the Python edition isn't going anywhere\u2014it gets regular fixes and features, and the Web UI is now production-ready. Ideas and PRs are welcome! Head over to the [issue templates](.github/ISSUE_TEMPLATE) or the [PR checklist](.github/pull_request_template.md) to get started.\n\n## \u26a1 Quickstart\nqBitrr supports Python 3.12+ on Linux, macOS, and Windows. Run it natively or in Docker\u2014whatever fits your stack.\n\n### \ud83d\udc0d Install with pip\n```bash\npython -m venv .venv\nsource .venv/bin/activate # Windows: .venv\\Scripts\\activate\npython -m pip install --upgrade pip\npython -m pip install qBitrr2\n\n# First run creates ~/config/config.toml\nqBitrr2\n```\n\n**Update later:**\n```bash\npython -m pip install --upgrade qBitrr2\n```\n\n**Or enable auto-updates** in `config.toml`:\n```toml\n[Settings]\nAutoUpdateEnabled = true\nAutoUpdateCron = \"0 3 * * 0\" # Weekly on Sunday at 3 AM\n```\n\n> \ud83d\udcdd **Note:** Auto-updates check GitHub releases for new versions. Only published (non-draft) releases trigger updates. Binary installations receive update notifications but require manual download.\n\n### \ud83d\udc33 Run with Docker\n**Minimal setup:**\n```bash\ndocker run -d \\\n --name qbitrr \\\n --tty \\\n -e TZ=Europe/London \\\n -p 6969:6969 \\\n -v /etc/localtime:/etc/localtime:ro \\\n -v /path/to/appdata/qbitrr:/config \\\n -v /path/to/completed/downloads:/completed_downloads:rw \\\n --restart unless-stopped \\\n feramance/qbitrr:latest\n```\n\nThe container automatically binds its WebUI to `0.0.0.0`; exposing `6969` makes the dashboard reachable at `http://<host>:6969/ui`.\n\n**Docker Compose example:**\n```yaml\nservices:\n qbitrr:\n image: feramance/qbitrr:latest\n container_name: qbitrr\n user: 1000:1000\n restart: unless-stopped\n tty: true\n environment:\n TZ: Europe/London\n ports:\n - \"6969:6969\"\n volumes:\n - /etc/localtime:/etc/localtime:ro\n - /path/to/appdata/qbitrr:/config\n - /path/to/completed/downloads:/completed_downloads:rw\n logging:\n driver: json-file\n options:\n max-size: 50m\n max-file: \"3\"\n depends_on:\n - qbittorrent\n - radarr\n - sonarr\n```\n\n> \u2139\ufe0f On first boot the container writes `config.toml` under `/config`. Update the values to match your mounts and restart the container.\n\n### \u2699\ufe0f Native Systemd Service\nFor Linux users running qBitrr natively (non-Docker), you can set up automatic startup and restart management using systemd.\n\n**Quick setup:**\n```bash\n# Install qBitrr\npip install qBitrr2\n\n# Copy systemd service file\nsudo cp qbitrr.service /etc/systemd/system/qbitrr.service\n\n# Enable and start\nsudo systemctl enable qbitrr\nsudo systemctl start qbitrr\n\n# Check status\nsudo systemctl status qbitrr\n```\n\n**Benefits:**\n- \u2705 Auto-start on boot\n- \u2705 Automatic restarts after crashes or updates\n- \u2705 Integrated logging with `journalctl`\n- \u2705 Resource limits and security hardening\n- \u2705 Works seamlessly with qBitrr's auto-update feature\n\n**See the full guide:** [SYSTEMD_SERVICE.md](SYSTEMD_SERVICE.md) for detailed setup instructions, troubleshooting, and security hardening options.\n\n## \ud83d\udee0\ufe0f Configuration\n\n### \ud83d\udcc2 Config Location\n- **Native install:** `~/config/config.toml`\n- **Docker:** `/config/config.toml`\n- **First run:** Auto-generates a template config file\n- **Manual generation:** `qbitrr --gen-config`\n\n### \ud83d\udd27 Essential Setup\n1. **Configure qBittorrent connection** in `[qBit]` section:\n - Set `Host`, `Port`, `UserName`, `Password`\n - qBittorrent 5.x requires `Version5 = true` (4.6.7 is the latest validated 4.x build)\n\n2. **Configure Arr instances** (Radarr/Sonarr/Lidarr):\n - Each instance needs: `URI`, `APIKey`, `Category`\n - **Important:** Use matching categories in Arr's download client settings\n - **Tagging:** Ensure Arr instances tag their downloads so qBitrr can track them\n\n3. **Set completed download folder:**\n ```toml\n [Settings]\n CompletedDownloadFolder = \"/path/to/completed\"\n ```\n\n4. **Enable logging** for troubleshooting:\n ```toml\n [Settings]\n Logging = true\n ConsoleLevel = \"INFO\" # or DEBUG for verbose output\n ```\n\n### \ud83d\udcd6 Configuration Reference\nSee [`config.example.toml`](config.example.toml) for comprehensive documentation of all settings, including:\n- Torrent health check thresholds\n- Search automation options\n- Seeding limits and tracker rules\n- Request system integration\n- WebUI settings\n- File filtering and exclusion rules\n\n## \ud83c\udfaf Feature Deep Dive\n\n### \ud83d\ude91 Torrent Health Monitoring\n\nqBitrr continuously monitors your torrents and takes intelligent action when problems arise.\n\n**Stalled Torrent Detection:**\n```toml\n[Radarr-Movies.Torrent]\nStalledDelay = 15 # Minutes before considering a torrent stalled\nReSearchStalled = true # Re-search before removing stalled torrents\nMaximumETA = 604800 # Max ETA in seconds (7 days)\nIgnoreTorrentsYoungerThan = 600 # Grace period for new torrents (10 min)\n```\n\n**Automatic Blacklisting:**\nWhen torrents fail or stall beyond thresholds, qBitrr:\n1. \u2705 Marks the release as failed in the Arr instance\n2. \u2705 Blacklists the release to prevent re-download\n3. \u2705 Optionally triggers an automatic re-search\n4. \u2705 Removes the failed torrent from qBittorrent\n\n**Smart Completion Rules:**\n```toml\n[Radarr-Movies.Torrent]\nMaximumDeletablePercentage = 0.99 # Don't delete torrents >99% complete\nDoNotRemoveSlow = true # Protect slow but active torrents\n```\n\n**File Verification:**\n```toml\n[Settings]\nFFprobeAutoUpdate = true # Auto-download FFprobe binary\n```\n- Validates media files are playable before import\n- Detects corrupted or fake files\n- Prevents broken media from being imported into Arr\n\n**Error Code Handling:**\n```toml\n[Radarr-Movies]\nArrErrorCodesToBlocklist = [\n \"Not an upgrade for existing movie file(s)\",\n \"Unable to determine if file is a sample\"\n]\n```\nAutomatically handle specific Arr error messages by removing failed files and triggering re-searches.\n\n---\n\n### \ud83d\udd0d Automated Search & Requests\n\n**Missing Media Search:**\n```toml\n[Radarr-Movies.EntrySearch]\nSearchMissing = true # Enable automated searching\nSearchLimit = 5 # Max concurrent searches\nSearchByYear = true # Order by release year\nSearchInReverse = false # Newest first (true = oldest first)\nSearchRequestsEvery = 300 # Delay between searches (seconds)\nSearchAgainOnSearchCompletion = true # Loop continuously\n```\n\n**Quality Upgrade Search:**\n```toml\n[Radarr-Movies.EntrySearch]\nDoUpgradeSearch = true # Search for better quality versions\nQualityUnmetSearch = true # Search for unmet quality profiles\nCustomFormatUnmetSearch = true # Search for better custom format scores\nForceMinimumCustomFormat = true # Auto-remove torrents below CF threshold\n```\n\n**Overseerr Integration:**\n```toml\n[Radarr-Movies.EntrySearch.Overseerr]\nSearchOverseerrRequests = true\nOverseerrURI = \"http://overseerr:5055\"\nOverseerrAPIKey = \"your-api-key\"\nApprovedOnly = true # Only process approved requests\nIs4K = false # Set true for 4K Arr instances\n```\n\n**Ombi Integration:**\n```toml\n[Radarr-Movies.EntrySearch.Ombi]\nSearchOmbiRequests = true\nOmbiURI = \"http://ombi:3579\"\nOmbiAPIKey = \"your-api-key\"\nApprovedOnly = true\n```\n\n**Smart Search Modes (Sonarr):**\n```toml\n[Sonarr-TV.EntrySearch]\nSearchBySeries = \"smart\" # auto | true (series) | false (episode)\n# smart: Series search for full seasons, episode search for singles\nPrioritizeTodaysReleases = true # Search today's episodes first (RSS-like)\nAlsoSearchSpecials = false # Include season 00 episodes\nUnmonitored = false # Include unmonitored items\n```\n\n**Temporary Quality Profiles:**\n```toml\n[Radarr-Movies.EntrySearch]\nUseTempForMissing = true\nKeepTempProfile = false\nMainQualityProfile = [\"Ultra-HD\", \"HD-1080p\"]\nTempQualityProfile = [\"Web-DL\", \"HDTV-720p\"]\n# Searches missing items with temp profile, switches back after import\n```\n\n---\n\n### \ud83d\udcca Quality Management\n\n**RSS Sync Automation:**\n```toml\n[Radarr-Movies]\nRssSyncTimer = 5 # Minutes between RSS feed refreshes (0 = disabled)\n```\nKeeps Arr instances checking indexers for new releases regularly.\n\n**Queue Refresh:**\n```toml\n[Radarr-Movies]\nRefreshDownloadsTimer = 5 # Minutes between queue updates (0 = disabled)\n```\nEnsures Arr instances stay in sync with qBittorrent's download state.\n\n**Import Mode:**\n```toml\n[Radarr-Movies]\nimportMode = \"Auto\" # Auto | Move | Copy\n```\n- **Auto:** Let Arr decide based on its settings\n- **Move:** Move files from download folder to library\n- **Copy:** Copy files (preserves seeding torrents)\n\n**Custom Format Score Enforcement:**\nWhen `ForceMinimumCustomFormat = true`, qBitrr automatically removes torrents that don't meet the minimum custom format score defined in your Arr quality profile.\n\n---\n\n### \ud83c\udf31 Seeding & Tracker Control\n\n**Global Seeding Limits:**\n```toml\n[Radarr-Movies.Torrent.SeedingMode]\nDownloadRateLimitPerTorrent = -1 # -1 = unlimited, or KB/s\nUploadRateLimitPerTorrent = -1 # -1 = unlimited, or KB/s\nMaxUploadRatio = 2.0 # Stop seeding at 2.0 ratio\nMaxSeedingTime = 604800 # Stop after 7 days (seconds)\nRemoveTorrent = 3 # 1=ratio, 2=time, 3=either, 4=both, -1=never\n```\n\n**Per-Tracker Settings:**\n```toml\n[[Radarr-Movies.Torrent.Trackers]]\nName = \"MyTracker\"\nPriority = 10 # Higher = processed first\nURI = \"https://tracker.example/announce\"\nMaximumETA = 18000 # Override global MaxETA for this tracker\nDownloadRateLimit = 5000 # KB/s limit for this tracker\nUploadRateLimit = 1000 # KB/s limit for this tracker\nMaxUploadRatio = 1.5 # Tracker-specific ratio limit\nMaxSeedingTime = 86400 # Tracker-specific time limit (1 day)\nAddTrackerIfMissing = true # Inject this tracker into matching torrents\nRemoveIfExists = false # Remove this tracker if found\nSuperSeedMode = true # Enable super seeding for this tracker\nAddTags = [\"private\", \"MyTracker\"] # Auto-tag matching torrents\n```\n\n**Tracker Cleanup:**\n```toml\n[Radarr-Movies.Torrent.SeedingMode]\nRemoveDeadTrackers = true\nRemoveTrackerWithMessage = [\n \"skipping tracker announce (unreachable)\",\n \"No such host is known\",\n \"unsupported URL protocol\"\n]\n```\n\n**File Filtering:**\n```toml\n[Radarr-Movies.Torrent]\nCaseSensitiveMatches = false\nFolderExclusionRegex = [\"\\\\bextras?\\\\b\", \"\\\\bsamples?\\\\b\", \"\\\\bfeaturettes?\\\\b\"]\nFileNameExclusionRegex = [\"\\\\bsample\\\\b\", \"\\\\btrailer\\\\b\"]\nFileExtensionAllowlist = [\".mp4\", \".mkv\", \".avi\", \".sub\", \".srt\"]\nAutoDelete = false # Auto-delete non-playable files (.exe, .png, etc.)\n```\n\n---\n\n### \ud83d\udcbe Disk Space Management\n\n**Free Space Monitoring:**\n```toml\n[Settings]\nFreeSpace = \"50G\" # Pause when <50GB free (K/M/G/T units)\nFreeSpaceFolder = \"/downloads\" # Path to monitor\nAutoPauseResume = true # Required for FreeSpace to work\n```\n\n**How it works:**\n1. \ud83d\udcca Continuously monitors specified folder\n2. \u23f8\ufe0f Pauses **all** torrents when space falls below threshold\n3. \u25b6\ufe0f Auto-resumes when space is reclaimed\n4. \ud83d\udd14 Logs warnings when approaching limit\n\n**Disable monitoring:**\n```toml\n[Settings]\n### \ud83d\udd04 Auto-Updates & Restarts\n\nqBitrr can automatically update itself by checking GitHub releases for new versions. The update behavior varies by installation type.\n\n#### \ud83d\udd0d How Updates Work\n\n**Update Detection:**\n1. \ud83d\udce1 Queries GitHub API for latest **published** (non-draft) release\n2. \ud83d\udd22 Compares release version with current version using semantic versioning\n3. \u23e9 Skips prereleases (beta, rc, alpha) by default\n4. \ud83d\udce6 Only updates when a newer **stable** version is available\n\n**Installation Types:**\n\n| Type | Detection | Update Method | Version Control |\n|------|-----------|---------------|-----------------|\n| **Git** | `.git` directory exists | `git checkout <tag>` or `git pull` | Checks out specific release tag |\n| **PyPI** | Installed via pip | `pip install qBitrr2==<version>` | Installs exact version from PyPI |\n| **Binary** | PyInstaller executable | Notification only | Logs download URL for manual update |\n\n**Why different methods?**\n- **Git installations** can checkout specific tags for precise version control\n- **PyPI installations** can pin to exact versions for reliability\n- **Binary installations** cannot self-update (would require replacing running executable), so qBitrr logs the download URL and version info for manual update\n\n---\n\n#### \u2699\ufe0f Configuration\n\n**Basic Setup:**\n```toml\n[Settings]\nAutoUpdateEnabled = true\nAutoUpdateCron = \"0 3 * * 0\" # Cron expression (default: Sunday 3 AM)\n```\n\n**Cron Expression Examples:**\n```toml\n\"0 3 * * 0\" # Every Sunday at 3:00 AM\n\"0 */6 * * *\" # Every 6 hours\n\"0 0 * * *\" # Daily at midnight\n\"0 2 * * 1-5\" # Weekdays at 2:00 AM\n```\n\n---\n\n#### \ud83d\udccb Update Process Flow\n\n**For Git & PyPI Installations:**\n\n1. **Check Phase:**\n - Fetch latest release from GitHub API\n - Validate release is not draft or prerelease\n - Compare versions (semantic versioning)\n - Skip if already on latest version\n\n2. **Download Phase:**\n - **Git:** `git fetch --tags && git checkout v<version>`\n - **PyPI:** `pip install --upgrade qBitrr2==<version>`\n\n3. **Verification Phase:**\n - Reload version information\n - Verify installed version matches target\n - Log warning if mismatch\n\n4. **Restart Phase:**\n - Gracefully shutdown (close DBs, flush logs)\n - Terminate child processes\n - Execute in-place restart via `os.execv()`\n - Maintain same PID (systemd-friendly)\n\n**For Binary Installations:**\n\n1. **Check Phase:** Same as above\n2. **Notification:** Logs message with download URL and instructions\n3. **Manual Update:** User downloads new binary from GitHub releases\n4. **No Auto-Restart:** User manually restarts after replacing binary\n\nExample binary update log:\n```\n[INFO] Update available: v5.4.2 -> v5.4.3\n[INFO] Binary installation detected - manual update required\n[INFO] Download: https://github.com/Feramance/qBitrr/releases/latest\n[INFO] Instructions:\n 1. Download the binary for your platform\n 2. Extract the archive\n 3. Replace current executable with new binary\n 4. Restart qBitrr\n```\n\n---\n\n#### \ud83d\udd27 Manual Updates\n\n**Via WebUI:**\n- Navigate to **Config tab**\n- Click **\"Check for Updates\"** to see available version\n- Click **\"Update Now\"** button\n- Confirm when prompted\n- Application restarts automatically (git/pip only)\n\n**Via Command Line:**\n\n```bash\n# Git installation\ncd /path/to/qBitrr\ngit fetch --tags\ngit checkout v5.4.3 # or: git pull\nqbitrr # restart\n\n# PyPI installation\npip install --upgrade qBitrr2\n# or: pip install qBitrr2==5.4.3 # specific version\nqbitrr # restart\n\n# Binary installation\n# Download from: https://github.com/Feramance/qBitrr/releases/latest\n# Extract and replace binary, then restart\n\n# Docker installation\ndocker pull feramance/qbitrr:latest\ndocker restart qbitrr\n# or: docker-compose pull && docker-compose up -d\n```\n\n---\n\n#### \ud83d\udd10 Security & Reliability\n\n**GitHub API Dependency:**\n- Auto-update requires GitHub API access\n- Rate limit: 60 requests/hour (unauthenticated)\n- Cron schedule should account for rate limits\n- Failures are logged but don't crash the application\n\n**Version Verification:**\n- After update, qBitrr verifies installed version\n- Helps catch failed updates or PyPI lag issues\n- Logs warning if version mismatch detected\n\n**Draft & Prerelease Handling:**\n- Draft releases are **always skipped** (unpublished)\n- Prereleases (beta/rc/alpha) are skipped by default\n- Useful for testing but not recommended for production\n\n**Rollback:**\n- Git installations: `git checkout <previous-tag>`\n- PyPI installations: `pip install qBitrr2==<previous-version>`\n- Binary installations: Keep backup of previous binary\n- No automatic rollback (manual intervention required)\n\n---\n\n#### \ud83d\ude80 Restart Mechanism\n\n**How it Works:**\n```python\nos.execv(sys.executable, [sys.executable] + sys.argv)\n```\n\n**Benefits:**\n- \u2705 **Same PID** \u2013 systemd doesn't detect a restart\n- \u2705 **No supervisor** \u2013 doesn't require external process manager\n- \u2705 **Clean state** \u2013 fresh Python interpreter, no memory leaks\n- \u2705 **Fast** \u2013 near-instant restart (< 1 second)\n\n**Supported Environments:**\n- \ud83d\udc33 **Docker** \u2013 container stays running, process restarts\n- \u2699\ufe0f **systemd** \u2013 service remains \"active\", no restart count increment\n- \ud83d\udcbb **Native** \u2013 works on Linux, macOS, Windows\n- \ud83e\ude9f **Windows** \u2013 handles different executable extensions (.exe, .cmd)\n\n**Graceful Shutdown:**\n1. Stop all Arr manager child processes\n2. Close database connections\n3. Flush log buffers to disk\n4. Release file locks\n5. Execute in-place restart\n\n---\n\n#### \ud83d\udee0\ufe0f Restart via API\n\n**Restart entire application:**\n```bash\ncurl -X POST http://localhost:6969/api/restart\n\n# With authentication\ncurl -X POST http://localhost:6969/api/restart \\\n -H \"Authorization: Bearer your-token\"\n```\n\n**Restart specific Arr manager:**\n```bash\ncurl -X POST http://localhost:6969/api/arr/radarr-movies/restart\n```\n\n---\n\n#### \u26a0\ufe0f Troubleshooting Updates\n\n**Update not triggering:**\n- \u2705 Check `AutoUpdateEnabled = true` in config\n- \u2705 Verify cron expression is valid (use [crontab.guru](https://crontab.guru))\n- \u2705 Check `Main.log` for GitHub API errors\n- \u2705 Ensure internet connectivity to api.github.com\n- \u2705 Check if already on latest version\n\n**Version mismatch after update:**\n- \u2705 Review logs for pip/git errors\n- \u2705 Manually verify installation: `pip show qBitrr2` or `git describe`\n- \u2705 Check if PyPI is behind GitHub releases (can take hours)\n- \u2705 Try manual update to force correct version\n\n**Binary updates not working:**\n- \u2139\ufe0f **Expected behavior** \u2013 binaries cannot auto-update\n- \u2705 Check logs for download URL\n- \u2705 Download matching binary for your platform\n- \u2705 Extract and replace current executable\n- \u2705 Ensure new binary has execute permissions (Unix)\n\n**Restart fails:**\n- \u2705 Check file permissions on qBitrr installation\n- \u2705 Review systemd journal if using systemd\n- \u2705 Verify no file locks preventing restart\n- \u2705 Check disk space for logs and databases\n- \u2705 Manual restart: Stop service, start again\n\n**For systemd users:** See [SYSTEMD_SERVICE.md](SYSTEMD_SERVICE.md) for automatic restart configuration with `Restart=always`.\n\n---\n\ncurl -X POST http://localhost:6969/api/arr/radarr-movies/restart\n```\n\n**For systemd users:** See [SYSTEMD_SERVICE.md](SYSTEMD_SERVICE.md) for automatic restart configuration.\n\n---\n\n## \ud83d\udda5\ufe0f Built-in Web UI\nThe React + Vite dashboard provides complete visibility and control over your qBitrr instance.\n\n### \ud83c\udf10 Access & Authentication\n- **Default URL:** `http://<host>:6969/ui`\n- **Custom host/port:** Configure in `config.toml`:\n ```toml\n [WebUI]\n Host = \"0.0.0.0\" # Bind address (0.0.0.0 for all interfaces)\n Port = 6969 # Web server port\n ```\n- **Authentication:** Protect API endpoints with bearer token:\n ```toml\n [WebUI]\n Token = \"your-secret-token\"\n ```\n When set, all `/api/*` endpoints require `Authorization: Bearer <token>` header.\n The UI itself uses unauthenticated `/web/*` endpoints.\n\n### \ud83d\uddc2\ufe0f Dashboard Tabs\n\n**\ud83d\udcca Processes Tab:**\n- View all running Arr manager processes\n- See current activity and search status\n- Monitor queue counts and metrics\n- Restart individual processes or all at once\n\n**\ud83d\udcdd Logs Tab:**\n- Real-time log viewer with filtering\n- View `Main.log`, `WebUI.log`, and per-Arr logs\n- Search and navigate large log files\n- Download logs for troubleshooting\n\n**\ud83c\udfac Radarr/Sonarr/Lidarr Tabs:**\n- Browse your media library with advanced filtering\n- Filter by year range, quality status, monitored state\n- See custom format scores and upgrade availability\n- Identify missing media and quality issues\n- View request status for Overseerr/Ombi items\n\n**\u2699\ufe0f Config Tab:**\n- Edit configuration directly in the UI\n- Trigger manual updates\n- View version and changelog\n- Rebuild Arr metadata\n- Restart application\n\n### \ud83c\udfa8 Customization\n```toml\n[WebUI]\nTheme = \"dark\" # or \"light\"\nLiveArr = true # Enable live updates for Arr views\nGroupSonarr = true # Group episodes by series\nGroupLidarr = true # Group albums by artist\n```\n\n### \ud83e\uddea Development\nThe WebUI source lives in `webui/`:\n```bash\ncd webui\nnpm ci # Install dependencies\nnpm run dev # Dev server with HMR at localhost:5173\nnpm run lint # ESLint check\nnpm run build # Build for production\n```\nBuild outputs to `webui/dist/`, which gets bundled into `qBitrr/static/`.\n\n**API Documentation:** See [API_DOCUMENTATION.md](API_DOCUMENTATION.md) for complete API reference.\n\n---\n\n## \ud83d\udd01 Day-to-day Operations\n\n### \ud83d\udd04 Restart & Rebuild\n- **Restart application:** WebUI \u2192 Config tab \u2192 \"Restart All\" button\n- **Restart individual Arr manager:** WebUI \u2192 Processes tab \u2192 Click restart icon\n- **Rebuild Arr metadata:** WebUI \u2192 Config tab \u2192 \"Rebuild Arrs\" button\n- **API endpoints:**\n ```bash\n POST /api/restart # Restart qBitrr\n POST /api/arr/<category>/restart # Restart specific manager\n POST /api/arr/rebuild # Rebuild all Arr caches\n ```\n\n### \ud83d\udccb Monitoring\n- **Logs location:** `~/logs/` (native) or `/config/logs` (Docker)\n- **Log files:**\n - `Main.log` \u2013 Main application logs\n - `WebUI.log` \u2013 Web interface logs\n - `<CategoryName>.log` \u2013 Per-Arr instance logs\n- **View in UI:** WebUI \u2192 Logs tab \u2192 Select log file\n- **View in terminal:**\n ```bash\n # Native\n tail -f ~/logs/Main.log\n\n # Docker\n docker logs -f qbitrr\n docker exec qbitrr tail -f /config/logs/Main.log\n\n # Systemd\n sudo journalctl -u qbitrr -f\n ```\n\n### \ud83d\udd0d Request Integration\nOnce configured, qBitrr automatically:\n1. \ud83d\udce5 Polls Overseerr/Ombi for new requests\n2. \ud83d\udd0d Searches requested items in Arr instances\n3. \u2b50 Prioritizes requests over general missing media searches\n4. \ud83d\udcca Identifies requests in WebUI Arr tabs with `isRequest` flag\n\n### \ud83d\udee0\ufe0f Special Categories\nqBitrr monitors special qBittorrent categories for manual intervention:\n\n**Failed Category:**\n```toml\n[Settings]\nFailedCategory = \"failed\"\n```\nManually move torrents here to mark them as failed and trigger blacklisting + re-search.\n\n**Recheck Category:**\n```toml\n[Settings]\nRecheckCategory = \"recheck\"\n```\nManually move torrents here to trigger a proper recheck operation.\n\n### \ud83c\udff7\ufe0f Tagless Operation\n```toml\n[Settings]\nTagless = true\n```\nRun qBitrr without requiring Arr instances to tag their torrents. Less precise but works without Arr configuration changes.\n\n---\n\n## \ud83c\udd98 Troubleshooting\n\n### \ud83d\udc1b Common Issues\n\n**Torrents not being processed:**\n1. \u2705 Verify Arr instance is using the correct **category** in download client settings\n2. \u2705 Ensure Arr instance **tags** match qBitrr's category configuration\n3. \u2705 Check `IgnoreTorrentsYoungerThan` \u2013 new torrents have a grace period\n4. \u2705 Enable debug logging: `ConsoleLevel = \"DEBUG\"`\n5. \u2705 Check category-specific log file in `~/logs/` or `/config/logs/`\n\n**Imports not triggering:**\n1. \u2705 Verify `CompletedDownloadFolder` path is correct and accessible\n2. \u2705 Check file extensions against `FileExtensionAllowlist`\n3. \u2705 Review `FolderExclusionRegex` and `FileNameExclusionRegex` for over-matching\n4. \u2705 Enable FFprobe logging to see media validation results\n5. \u2705 Check Arr instance has proper path mappings (especially in Docker)\n\n**Search not finding releases:**\n1. \u2705 Verify `SearchMissing = true` in the EntrySearch section\n2. \u2705 Check `SearchLimit` isn't too low for your queue\n3. \u2705 Review `SearchByYear` and `SearchInReverse` settings\n4. \u2705 Ensure Arr instance has indexers configured and working\n5. \u2705 Check for rate limiting in Arr instance logs\n\n**High CPU/memory usage:**\n1. \u2705 Reduce `SearchLimit` to lower concurrent searches\n2. \u2705 Increase `LoopSleepTimer` to slow down processing\n3. \u2705 Disable `DoUpgradeSearch` if not needed\n4. \u2705 Set `LiveArr = false` in WebUI config to reduce refresh overhead\n\n**Docker path issues:**\n1. \u2705 Ensure volume mounts match between qBittorrent, Arr, and qBitrr\n2. \u2705 Use consistent paths across all containers\n3. \u2705 Example: All containers should see `/downloads` as the same physical path\n\n**Updates failing:**\n1. \u2705 Check internet connectivity\n2. \u2705 Verify pip/Python installation is writable\n3. \u2705 Review update logs in `Main.log` or `WebUI.log`\n4. \u2705 Manual update: `pip install --upgrade qBitrr2` (native) or pull new Docker image\n\n### \ud83d\udcca Enable Debug Logging\n```toml\n[Settings]\nLogging = true\nConsoleLevel = \"DEBUG\" # TRACE for even more detail\n```\nLogs output to:\n- **Native:** `~/logs/`\n- **Docker:** `/config/logs/`\n- **Systemd:** `sudo journalctl -u qbitrr -n 100`\n\n### \ud83d\udc1e Reporting Issues\nWhen reporting bugs:\n\n1. **Enable file logging** and reproduce the issue\n2. **Collect information:**\n - qBitrr version: `qBitrr2 --version` or Docker tag\n - OS and deployment method (Docker/native/systemd)\n - qBittorrent version and API version (4.x vs 5.x)\n - Arr instance versions (Radarr/Sonarr/Lidarr)\n - Request tool versions (Overseerr/Ombi) if applicable\n3. **Grab relevant log snippets** (scrub API keys and tokens!)\n4. **Open an issue** using the [bug report template](.github/ISSUE_TEMPLATE/bug_report.yml)\n5. **Include:**\n - Clear reproduction steps\n - Expected vs. actual behavior\n - Relevant config sections (with secrets removed)\n - Error messages and stack traces\n\n### \ud83d\udca1 Feature Requests\nHave an idea? Submit it via the [feature request template](.github/ISSUE_TEMPLATE/feature_request.yml)!\n\n### \ud83d\udcda Additional Resources\n- **API Documentation:** [API_DOCUMENTATION.md](API_DOCUMENTATION.md)\n- **Systemd Setup:** [SYSTEMD_SERVICE.md](SYSTEMD_SERVICE.md)\n- **Example Config:** [config.example.toml](config.example.toml)\n- **GitHub Issues:** [Search existing issues](https://github.com/Feramance/qBitrr/issues)\n\n---\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions from the community! Whether it's code, documentation, bug reports, or feature ideas, your help makes qBitrr better.\n\n### \ud83d\udd27 Development Setup\n\n**Python Backend:**\n```bash\n# Clone the repo\ngit clone https://github.com/Feramance/qBitrr.git\ncd qBitrr\n\n# Create virtual environment\nmake newenv\n# or: python -m venv .venv && source .venv/bin/activate\n\n# Install dependencies\nmake syncenv\n# or: pip install -e .[all]\n\n# Run linting and formatting\nmake reformat\n# or: pre-commit run --all-files\n```\n\n**TypeScript/React WebUI:**\n```bash\ncd webui\nnpm ci # Install exact versions from package-lock.json\nnpm run dev # Dev server at localhost:5173\nnpm run lint # ESLint check\nnpm run build # Build for production\n```\n\n### \ud83d\udcdd Before Submitting a PR\n\n1. \u2705 Read the [pull request template](.github/pull_request_template.md)\n2. \u2705 **Format code:**\n - Python: `make reformat` or `pre-commit run --all-files`\n - TypeScript: `npm run lint` in `webui/`\n3. \u2705 **Test your changes:**\n - Run against live qBittorrent + Arr instances\n - Test in both Docker and native environments if possible\n4. \u2705 **Update documentation:**\n - Add/update relevant sections in README.md\n - Update `config.example.toml` if adding config options\n - Document API changes in `API_DOCUMENTATION.md`\n5. \u2705 **Clean commit history:**\n - Use descriptive commit messages\n - Follow [conventional commits](https://www.conventionalcommits.org/) format\n - Squash WIP commits before submitting\n\n### \ud83d\udca1 Contribution Ideas\n\n- \ud83d\udc1b **Bug fixes** \u2013 check [open issues](https://github.com/Feramance/qBitrr/issues)\n- \u2728 **Features** \u2013 see [feature requests](https://github.com/Feramance/qBitrr/labels/enhancement)\n- \ud83d\udcda **Documentation** \u2013 improve guides, add examples, fix typos\n- \ud83c\udf0d **Translations** \u2013 help internationalize the WebUI\n- \ud83e\uddea **Testing** \u2013 add test coverage, validate edge cases\n\n**Unsure if an idea fits?** Open a [feature request](.github/ISSUE_TEMPLATE/feature_request.yml) first and let's discuss!\n\n### \ud83d\udcdc Code Guidelines\n\nSee [CONTRIBUTION.md](CONTRIBUTION.md) for comprehensive coding standards and architecture details.\n\n**Quick summary:**\n- **Python:** Black formatting (99 chars), type hints required, PEP 8 naming\n- **TypeScript:** ESLint strict mode, explicit types, functional components only\n- **Commits:** LF line endings, no trailing whitespace, EOF newline required\n- **Errors:** Inherit from `qBitManagerError`, provide actionable messages\n\n---\n\n## \u2764\ufe0f Support\n\n### \ud83c\udf1f Show Your Support\n- \u2b50 **Star the repo** \u2013 helps others discover qBitrr\n- \ud83d\udc1b **Report bugs** \u2013 attach logs so we can fix issues faster\n- \ud83d\udcac **Share feedback** \u2013 tell us what works and what doesn't\n- \ud83d\udee0\ufe0f **Contribute** \u2013 code, docs, translations, or just good vibes\n\n### \ud83d\udcb0 Sponsor Development\nIf qBitrr saves you time and headaches, consider supporting its development:\n\n- \ud83c\udfa8 [Patreon](https://patreon.com/qBitrr) \u2013 monthly support\n- \ud83d\udcb8 [PayPal](https://www.paypal.me/feramance) \u2013 one-time donations\n\nYour support keeps qBitrr maintained, updated, and improving. Thank you! \ud83d\ude4f\n\n---\n\n## \ud83d\udcc4 License\n\nqBitrr is released under the [MIT License](LICENSE).\n\n**TL;DR:** Use it, modify it, share it\u2014commercially or personally. Just keep the copyright notice and don't blame us if things break. \ud83d\ude0a\n\n---\n\n## \ud83d\udd17 Quick Links\n\n- \ud83d\udce6 [PyPI Package](https://pypi.org/project/qBitrr2/)\n- \ud83d\udc33 [Docker Hub](https://hub.docker.com/r/feramance/qbitrr)\n- \ud83d\udcda [API Documentation](API_DOCUMENTATION.md)\n- \u2699\ufe0f [Systemd Setup Guide](SYSTEMD_SERVICE.md)\n- \ud83d\udcdd [Example Configuration](config.example.toml)\n- \ud83d\udc1b [Report a Bug](.github/ISSUE_TEMPLATE/bug_report.yml)\n- \u2728 [Request a Feature](.github/ISSUE_TEMPLATE/feature_request.yml)\n- \ud83d\udcac [Discussions](https://github.com/Feramance/qBitrr/discussions)\n\n---\n\n<div align=\"center\">\n\n**Made with \u2764\ufe0f by the qBitrr community**\n\n</div>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Intelligent automation for qBittorrent and *Arr apps (Radarr/Sonarr/Lidarr) - health monitoring, instant imports, quality upgrades, request integration",
"version": "5.4.5",
"project_urls": {
"Changelog": "https://github.com/Feramance/qBitrr/blob/master/CHANGELOG.md",
"Docker Hub": "https://hub.docker.com/r/feramance/qbitrr",
"Documentation": "https://github.com/Feramance/qBitrr/blob/master/API_DOCUMENTATION.md",
"Homepage": "https://github.com/Feramance/qBitrr",
"Issue Tracker": "https://github.com/Feramance/qBitrr/issues",
"PyPI": "https://pypi.org/project/qBitrr2/",
"Source Code": "https://github.com/Feramance/qBitrr",
"Systemd Guide": "https://github.com/Feramance/qBitrr/blob/master/SYSTEMD_SERVICE.md"
},
"split_keywords": [
"qbittorrent",
" radarr",
" sonarr",
" lidarr",
" arr",
" automation",
" torrent",
" media",
" plex",
" jellyfin",
" overseerr",
" ombi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c598f2bba0838fb5c4744493abf72ccfcd80f4f3077a845a6e5c64fe8d87f0fb",
"md5": "be9331df0a75a6d9d5041d4221055e39",
"sha256": "6f986b46cc59446532337c4f323c4080962a18e26c2136b81f8031f85065aad0"
},
"downloads": -1,
"filename": "qbitrr2-5.4.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "be9331df0a75a6d9d5041d4221055e39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.12",
"size": 968697,
"upload_time": "2025-11-05T11:36:29",
"upload_time_iso_8601": "2025-11-05T11:36:29.153875Z",
"url": "https://files.pythonhosted.org/packages/c5/98/f2bba0838fb5c4744493abf72ccfcd80f4f3077a845a6e5c64fe8d87f0fb/qbitrr2-5.4.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "814b0bb8e3da7c79958e1b28ac1d9a9acf00b005af702b9b47d56a7c44ab9464",
"md5": "c85b79911930ad6eccd8d3f46173d47e",
"sha256": "f7b1363a84dcf1607efb8aec6bbf475e1209f8de5ba9341359a3630147537a84"
},
"downloads": -1,
"filename": "qbitrr2-5.4.5.tar.gz",
"has_sig": false,
"md5_digest": "c85b79911930ad6eccd8d3f46173d47e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.12",
"size": 986737,
"upload_time": "2025-11-05T11:36:30",
"upload_time_iso_8601": "2025-11-05T11:36:30.749857Z",
"url": "https://files.pythonhosted.org/packages/81/4b/0bb8e3da7c79958e1b28ac1d9a9acf00b005af702b9b47d56a7c44ab9464/qbitrr2-5.4.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 11:36:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Feramance",
"github_project": "qBitrr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "qBitrr2",
"specs": [
[
"==",
"4.10.28"
]
]
}
],
"lcname": "qbitrr2"
}
JSON
