qbit-guard¶

A zero-dependency Python guard for qBittorrent that provides intelligent torrent management with pre-air checking and ISO/BDMV cleanup.

Get Started
Install and configure qbit-guard in minutes
Installation
Configuration
Environment-driven configuration with sensible defaults
Configuration
Examples
Real-world deployment scenarios and configurations
Examples
Support
Troubleshooting guide and development resources
Troubleshooting

Features¶

Intelligent Torrent Management

qbit-guard automatically manages your torrents with smart filtering and cleanup rules.

Pre-air GateISO/BDMV CleanupSmart BlocklistingCross-verificationqBittorrent SupportZero DependenciesSelective File Control

Stops new TV torrents and unreleased movies

TV Shows: Checks airDateUtc via Sonarr with configurable grace/cap windows
Movies: Checks release dates via Radarr (digitalRelease, physicalRelease, inCinemas)
Supports release group / indexer / tracker whitelisting
Blocks too-early releases automatically
Integrates with Sonarr/Radarr for metadata validation

Removes disc-image-only torrents

Detects ISO/IMG/MDF/NRG/CUE/BIN files
Identifies BDMV and VIDEO_TS folders
Preserves torrents with keepable video files
Configurable minimum file size thresholds

Automated blocklist management

Blocklists in Sonarr/Radarr before deletion
Uses deduped history (single "grabbed" record per unique release)
Queue failover if history endpoint times out
Prevents duplicate downloads

Optional internet verification

TVmaze, TheTVDB, and/or TMDB integration
Cross-checks Sonarr air dates and movie release dates
TMDB provides authoritative digital/physical release dates for movies
Improves accuracy of pre-air filtering for both TV and movies
No API keys required for TVmaze

Works with modern and legacy versions

qBittorrent 5.x - Preferred with start/stop support
qBittorrent 4.x - Uses resume/pause fallback
WebUI authentication support
Category-based filtering

Container-friendly and lightweight

Pure Python 3.8+ standard library
Environment variable configuration
Structured JSON logging to stdout
Minimal resource usage

Advanced file management

Selective file unchecking instead of full torrent deletion
Preserves wanted files while blocking unwanted extensions
Configurable partial download behavior
Tagged torrents for easy identification (guard:partial)

How it Works¶

flowchart TD
    A[Torrent Added] --> B{Category Check}
    B -->|Allowed| C[Stop & Tag: guard:stopped]
    B -->|Blocked| Z[Ignore]
    C --> D{Pre-air Gate}
    D -->|TV Show Category| E[Check Sonarr API]
    D -->|Movie Category| F[Check Radarr API]  
    D -->|Not Pre-air Category| G[Get Metadata]
    E --> E2[Optional: TVmaze/TVDB Check]
    F --> F2[Optional: TMDB Check]
    E2 --> H{TV Air Date Check}
    F2 --> I{Movie Release Date Check}
    H -->|Too Early| J[Blocklist & Delete TV]
    I -->|Too Early| K[Blocklist & Delete Movie]
    H -->|Allowed| G[Get Metadata]
    I -->|Allowed| G[Get Metadata]
    G --> L{Extension Policy}
    L -->|All Files Blocked| M[Blocklist & Delete]
    L -->|Some Files Blocked| N{Uncheck Blocked Files?}
    L -->|No Files Blocked| O{ISO/BDMV Check}
    N -->|Yes| P[Uncheck Files & Tag: guard:partial]
    N -->|No| M
    P --> O
    O -->|Disc Image Only| Q[Blocklist & Delete]
    O -->|Has Video| R[Tag: guard:allowed & Start]
    J --> S[Tag: trash:preair]
    K --> T[Tag: trash:preair-movie]
    M --> U[Tag: trash:ext]
    Q --> V[Tag: trash:iso]
    R --> W[Active Download]

Flow Steps

On add → torrent immediately stopped and tagged guard:stopped
Category filter → only QBIT_ALLOWED_CATEGORIES are processed
Pre-air gate:
- TV Shows (if Sonarr category): consult Sonarr (+ optional TVmaze/TVDB)
- Movies (if Radarr category): consult Radarr for release dates (+ optional TMDB cross-check)
- If blocked → blocklist in *arr, tag trash:preair or trash:preair-movie, delete torrent
- If allowed → continue
Metadata fetch → briefly start torrent to get file list, respect wait/budget limits, then stop
Extension policy → check files against allow/block lists:
- If all blocked → delete torrent (optional: tag trash:ext)
- If some blocked → uncheck blocked files, tag guard:partial, continue with allowed files
- If none blocked → continue
ISO/BDMV cleanup → if disc-image-only and no keepable video, blocklist + delete (tag trash:iso)
Start for real → tag guard:allowed and start torrent

Keepable Video Files

Files with extensions: .mkv .mp4 .m4v .avi .ts .m2ts .mov .webm and size ≥ threshold.

Requirements¶

Prerequisites

Ensure all services are properly networked and accessible between containers.

Component	Version	Purpose	Required
qBittorrent	5.x (4.x supported)	Torrent client	Required
Python	3.8+	Script mode only	Optional
Sonarr	v3+	TV pre-air checking	Optional
Radarr	v3+	Movie pre-air checking & ISO blocklisting	Optional
TMDB API	-	Movie release date verification	Optional
Network	-	Service connectivity	Required

Quick Start¶

Docker Compose (Recommended)Docker RunUNRAID (Easy Setup)Python Script

YAML
version: '3.8'
services:
  qbit-guard:
    image: ghcr.io/gengines/qbit-guard:latest
    container_name: qbit-guard
    restart: unless-stopped
    environment:
      - QBIT_HOST=http://qbittorrent:8080
      - QBIT_USER=admin
      - QBIT_PASS=your_password
      - QBIT_ALLOWED_CATEGORIES=tv-sonarr,radarr
      - ENABLE_PREAIR_CHECK=1
      - SONARR_URL=http://sonarr:8989
      - SONARR_APIKEY=your_api_key
      - # Pre-air checking for movies now uses ENABLE_PREAIR_CHECK (same as TV shows)
      - RADARR_URL=http://radarr:7878
      - RADARR_APIKEY=your_radarr_api_key
      - TMDB_APIKEY=your_tmdb_api_key  # Optional: for enhanced movie release date accuracy
      - ENABLE_ISO_CHECK=1
      - LOG_LEVEL=INFO
    networks: [arr-network]

networks:
  arr-network: { driver: bridge }

Bash
docker run -d \
  --name qbit-guard \
  --restart unless-stopped \
  --network arr-network \
  -e QBIT_HOST=http://qbittorrent:8080 \
  -e QBIT_USER=admin \
  -e QBIT_PASS=your_password \
  -e QBIT_ALLOWED_CATEGORIES=tv-sonarr,radarr \
  -e ENABLE_PREAIR_CHECK=1 \
  -e SONARR_URL=http://sonarr:8989 \
  -e SONARR_APIKEY=your_api_key \
  -e # Pre-air checking for movies now uses ENABLE_PREAIR_CHECK (same as TV shows) \
  -e RADARR_URL=http://radarr:7878 \
  -e RADARR_APIKEY=your_radarr_api_key \
  -e TMDB_APIKEY=your_tmdb_api_key \  # Optional: for enhanced movie release date accuracy
  -e ENABLE_ISO_CHECK=1 \
  -e LOG_LEVEL=INFO \
  ghcr.io/gengines/qbit-guard:latest

For UNRAID users - GUI-based configuration

Install via Community Applications:
- Open UNRAID web interface
- Navigate to Apps tab
- Search for "qbit-guard"
- Click Install
Configure through GUI:
- Repository: ghcr.io/gengines/qbit-guard:latest
- Network: Select your Docker network
- Environment Variables (configure via UNRAID template):
  - QBIT_HOST=http://qbittorrent:8080
  - QBIT_PASS=your_password
  - SONARR_APIKEY=your_api_key
  - RADARR_APIKEY=your_radarr_api_key
  - TMDB_APIKEY=your_tmdb_api_key (optional)

UNRAID Benefits

User-friendly GUI configuration, automatic container management, and seamless integration with other UNRAID apps.

Bash
# Download the script
wget https://github.com/GEngines/qbit-guard/raw/main/src/guard.py

# Set environment variables
export QBIT_HOST=http://localhost:8080
export QBIT_USER=admin
export QBIT_PASS=your_password
export QBIT_ALLOWED_CATEGORIES=tv-sonarr,radarr
export ENABLE_PREAIR_CHECK=1
export SONARR_URL=http://localhost:8989
export SONARR_APIKEY=your_api_key
export # Pre-air checking for movies now uses ENABLE_PREAIR_CHECK (same as TV shows)
export RADARR_URL=http://localhost:7878
export RADARR_APIKEY=your_radarr_api_key
export TMDB_APIKEY=your_tmdb_api_key  # Optional: for enhanced movie release date accuracy

# Run the script
python3 qbit_guard.py

Next Steps

After starting qbit-guard, check the logs to ensure it connects successfully to qBittorrent and any configured *arr services.

Documentation¶

Installation Guide - Detailed setup instructions
Configuration Guide - Complete configuration options
Environment Variables - Full variable reference
Examples - Real-world deployment scenarios
Development - Development and contribution guide
Troubleshooting - Common issues and solutions