All apps · 0 apps

qbit-guard

Overview

A zero-dependency Python guard for qBittorrent that blocks pre-air TV episodes (Sonarr), deletes ISO/BDMV-only torrents, and auto-blocklists bad releases in Sonarr/Radarr (with dedupe + queue failover). Runs on "torrent added", fetches metadata safely, and logs everything to stdout. Key Features: Pre-air gate (Sonarr): Stops new TV torrents, checks airDateUtc with configurable grace periods TMDB integration (Radarr): Verifies movie digital release dates to prevent pre-release downloads Extension policy: Allow/Block by file extension with configurable strategies Selective file unchecking: Optionally uncheck blocked files instead of deleting entire torrents ISO/BDMV cleaner: Removes disc-image-only torrents that lack keepable video content Smart blocklisting: Blocklists in Sonarr/Radarr before deletion using deduped history Internet cross-verification: Optional TVmaze, TheTVDB, and/or TMDB API integration Zero dependencies: No external libraries, just Python 3.8+ stdlib Container-friendly: All configuration via environment variables, logs to stdout

Readme

View on GitHub

qbit-guard

A zero-dependency Python guard for qBittorrent that blocks pre-air TV episodes (Sonarr) and unreleased movies (Radarr), deletes ISO/BDMV-only torrents, and auto-blocklists bad releases in Sonarr/Radarr (with dedupe + queue failover). Runs on "torrent added", fetches metadata safely, and logs everything to stdout.

Documentation

The full documentation has moved to: https://gengines.github.io/qbit-guard/

Please visit our GitHub Pages site for comprehensive documentation including:

Installation instructions
Configuration options
Docker deployment guides
Usage examples
Troubleshooting tips

Quick Links

Documentation: https://gengines.github.io/qbit-guard/
Docker Image: ghcr.io/gengines/qbit-guard:<tag>
UNRAID: Available in Community Applications as "qbit-guard" (or via binhex's version)
Repository: https://github.com/GEngines/qbit-guard

Key Features

Pre-air gate (Sonarr): Stops new TV torrents, checks airDateUtc with configurable grace periods
Pre-air gate (Radarr): Stops new movie torrents, checks release dates with configurable grace periods
Extension policy: Allow/Block by file extension with configurable strategies
ISO/BDMV cleaner: Removes disc-image-only torrents that lack keepable video content
Smart blocklisting: Blocklists in Sonarr/Radarr before deletion using deduped history
Internet cross-verification: Optional TVmaze and/or TheTVDB API integration
Zero dependencies: No external libraries, just Python 3.8+ stdlib
Container-friendly: All configuration via environment variables, logs to stdout

Install qbit-guard on Unraid in a few clicks.

Find qbit-guard in Community Apps on your Unraid server, review the template, and click Install. Unraid handles the Docker app or plugin setup from the published template.

Open the Apps tab on your Unraid server Search Community Apps for qbit-guard Review the template variables and paths Click Install

Explore Unraid OS

Related apps

Explore more like this

Explore all

Downloaders Utilities apps

Links

Projectgithub.com Supportgithub.com Registrygithub.com Templateraw.githubusercontent.com

Details

Repository

ghcr.io/gengines/qbit-guard

Registry

https://github.com/GEngines/qbit-guard/pkgs/container/qbit-guard

Last Updated2026-07-15

First Seen2025-08-28

Runtime arguments

Network: bridge
Shell: sh
Privileged: false
Extra Params: --restart unless-stopped

Template configuration

Variable: QBIT_HOSTVariable

qBittorrent WebUI URL

Target: QBIT_HOST
Default: http://127.0.0.1:8080

Variable: QBIT_USERVariable

qBittorrent WebUI username

Target: QBIT_USER
Default: admin

Variable: QBIT_PASSVariable

qBittorrent WebUI password

Target: QBIT_PASS
Default: adminadmin

Variable: QBIT_ALLOWED_CATEGORIESVariable

Comma-separated list of categories to process

Target: QBIT_ALLOWED_CATEGORIES
Default: radarr,tv-sonarr

Variable: QBIT_DELETE_FILESVariable

Delete files when removing torrents

Target: QBIT_DELETE_FILES
Default: true|false

Variable: QBIT_IGNORE_TLSVariable

Set to 1 to ignore SSL certificate errors

Target: QBIT_IGNORE_TLS
Default: 0|1

Variable: QBIT_DRY_RUNVariable

Set to 1 for testing mode (no actual deletions)

Target: QBIT_DRY_RUN
Default: 0|1

Variable: WATCH_POLL_SECONDSVariable

How often to check qBittorrent for new torrents (seconds)

Target: WATCH_POLL_SECONDS
Default: 3.0

Variable: WATCH_PROCESS_EXISTING_AT_STARTVariable

Process existing torrents when container starts (0 or 1)

Target: WATCH_PROCESS_EXISTING_AT_START
Default: 0|1

Variable: WATCH_RESCAN_KEYWORDVariable

Keyword in category/tags to force reprocessing

Target: WATCH_RESCAN_KEYWORD
Default: rescan

Variable: ENABLE_PREAIR_CHECKVariable

Enable pre-air checking for TV shows and movies (0 or 1)

Target: ENABLE_PREAIR_CHECK
Default: 1|0

Variable: SONARR_URLVariable

Sonarr base URL

Target: SONARR_URL
Default: http://127.0.0.1:8989

Variable: SONARR_APIKEYVariable

Sonarr API key

Target: SONARR_APIKEY

Variable: SONARR_CATEGORIESVariable

Categories to apply pre-air checks to

Target: SONARR_CATEGORIES
Default: tv-sonarr

Variable: EARLY_GRACE_HOURSVariable

Allow releases this many hours before air date

Target: EARLY_GRACE_HOURS
Default: 6

Variable: EARLY_HARD_LIMIT_HOURSVariable

Block releases more than this many hours early

Target: EARLY_HARD_LIMIT_HOURS
Default: 72

Variable: WHITELIST_OVERRIDES_HARD_LIMITVariable

Let whitelisted releases bypass hard limit (0 or 1)

Target: WHITELIST_OVERRIDES_HARD_LIMIT
Default: 0|1

Variable: EARLY_WHITELIST_GROUPSVariable

Comma-separated list of trusted release groups

Target: EARLY_WHITELIST_GROUPS

Variable: EARLY_WHITELIST_INDEXERSVariable

Comma-separated list of trusted indexers

Target: EARLY_WHITELIST_INDEXERS

Variable: EARLY_WHITELIST_TRACKERSVariable

Comma-separated list of trusted trackers

Target: EARLY_WHITELIST_TRACKERS

Variable: RESUME_IF_NO_HISTORYVariable

Proceed if Sonarr history not found (0 or 1)

Target: RESUME_IF_NO_HISTORY
Default: 1|0

Variable: SONARR_TIMEOUT_SECVariable

HTTP timeout for Sonarr API calls

Target: SONARR_TIMEOUT_SEC
Default: 45

Variable: SONARR_RETRIESVariable

Retry attempts for Sonarr operations

Target: SONARR_RETRIES
Default: 3

Variable: RADARR_URLVariable

Radarr base URL

Target: RADARR_URL
Default: http://127.0.0.1:7878

Variable: RADARR_APIKEYVariable

Radarr API key

Target: RADARR_APIKEY

Variable: RADARR_CATEGORIESVariable

Categories for Radarr blocklisting and pre-air checks

Target: RADARR_CATEGORIES
Default: radarr

Variable: RADARR_TIMEOUT_SECVariable

HTTP timeout for Radarr API calls

Target: RADARR_TIMEOUT_SEC
Default: 45

Variable: RADARR_RETRIESVariable

Retry attempts for Radarr operations

Target: RADARR_RETRIES
Default: 3

Variable: INTERNET_CHECK_PROVIDERVariable

Provider selection: off, tvmaze, tvdb, or both

Target: INTERNET_CHECK_PROVIDER
Default: tvmaze|tvdb|both|off

Variable: TVMAZE_BASEVariable

TVmaze API base URL

Target: TVMAZE_BASE
Default: https://api.tvmaze.com

Variable: TVMAZE_TIMEOUT_SECVariable

HTTP timeout for TVmaze API calls

Target: TVMAZE_TIMEOUT_SEC
Default: 8

Variable: TVDB_BASEVariable

TheTVDB API base URL

Target: TVDB_BASE
Default: https://api4.thetvdb.com/v4

Variable: TVDB_APIKEYVariable

TheTVDB API key (required for TVDB)

Target: TVDB_APIKEY

Variable: TVDB_PINVariable

TheTVDB PIN (optional)

Target: TVDB_PIN

Variable: TVDB_LANGUAGEVariable

Language code for TheTVDB

Target: TVDB_LANGUAGE
Default: eng

Variable: TVDB_ORDERVariable

Episode order: default or official

Target: TVDB_ORDER
Default: default|official

Variable: TVDB_TIMEOUT_SECVariable

HTTP timeout for TheTVDB API calls

Target: TVDB_TIMEOUT_SEC
Default: 8

Variable: TVDB_BEARERVariable

Reuse existing bearer token (optional)

Target: TVDB_BEARER

Variable: TMDB_APIKEYVariable

TMDB API key (required for movie digital release verification)

Target: TMDB_APIKEY

Variable: TMDB_BASEVariable

TMDB API base URL

Target: TMDB_BASE
Default: https://api.themoviedb.org/3

Variable: TMDB_TIMEOUT_SECVariable

HTTP timeout for TMDB API calls

Target: TMDB_TIMEOUT_SEC
Default: 8

Variable: TMDB_LANGUAGEVariable

Language code for TMDB

Target: TMDB_LANGUAGE
Default: en-US

Variable: ENABLE_ISO_CHECKVariable

Enable ISO/disc image cleanup (0 or 1)

Target: ENABLE_ISO_CHECK
Default: 1|0

Variable: MIN_KEEPABLE_VIDEO_MBVariable

Minimum size for video files to keep (MB)

Target: MIN_KEEPABLE_VIDEO_MB
Default: 50

Variable: METADATA_POLL_INTERVALVariable

Seconds between file list checks during metadata fetching

Target: METADATA_POLL_INTERVAL
Default: 1.5

Variable: METADATA_MAX_WAIT_SECVariable

Max wait for metadata resolution (0 = infinite)

Target: METADATA_MAX_WAIT_SEC
Default: 0

Variable: METADATA_DOWNLOAD_BUDGET_BYTESVariable

Max bytes to download during metadata wait (0 = no limit)

Target: METADATA_DOWNLOAD_BUDGET_BYTES
Default: 0

Variable: GUARD_EXT_STRATEGYVariable

Extension strategy: block or allow

Target: GUARD_EXT_STRATEGY
Default: block

Variable: GUARD_ALLOWED_EXTSVariable

Comma-separated list of allowed extensions (for allow mode)

Target: GUARD_ALLOWED_EXTS

Variable: GUARD_BLOCKED_EXTSVariable

Comma-separated list of blocked extensions (overrides defaults in block mode)

Target: GUARD_BLOCKED_EXTS

Variable: GUARD_EXT_DELETE_IF_ALL_BLOCKEDVariable

Delete only if all files are disallowed (0 or 1)

Target: GUARD_EXT_DELETE_IF_ALL_BLOCKED
Default: 1|0

Variable: GUARD_EXT_DELETE_IF_ANY_BLOCKEDVariable

Delete if any file is disallowed (0 or 1)

Target: GUARD_EXT_DELETE_IF_ANY_BLOCKED
Default: 0|1

Variable: GUARD_UNCHECK_BLOCKED_FILESVariable

Uncheck blocked files instead of deleting torrent (0 or 1)

Target: GUARD_UNCHECK_BLOCKED_FILES
Default: 0|1

Variable: GUARD_EXT_VIOLATION_TAGVariable

Tag applied to torrents deleted for extension violations

Target: GUARD_EXT_VIOLATION_TAG
Default: trash:ext

Variable: GUARD_DISC_EXTSVariable

Disc image extensions

Target: GUARD_DISC_EXTS
Default: iso,img,mdf,nrg,cue,bin

Variable: GUARD_EXTS_FILEVariable

Path to JSON config file (optional)

Target: GUARD_EXTS_FILE

Variable: LOG_LEVELVariable

Logging verbosity: INFO, DEBUG, or DETAILED

Target: LOG_LEVEL
Default: INFO|DEBUG|DETAILED

Variable: USER_AGENTVariable

HTTP User-Agent string for API calls

Target: USER_AGENT
Default: qbit-guard/2.0

Library

Curated

Categories

qbit-guard

Overview

Readme

qbit-guard

Documentation

Quick Links

Key Features

Install qbit-guard on Unraid in a few clicks.

Categories

Related apps

Links

Details

Runtime arguments

Template configuration