qBitTorrent Cleanup Script

This repository now has one active implementation and two Bash scripts kept only for legacy compatibility.

Repository Layout

• Python/qBitTorrent-Cleanup.py

  • The primary and recommended implementation.
  • Uses the qBitTorrent WebUI API through qbittorrent-api.
  • Intended for qBitTorrent 4.5+ and compatible with qBitTorrent 5.x.

• Bash/4.5+/qBitTorrent-Cleanup.sh

  • Legacy Bash script for qBitTorrent 4.5 and newer.
  • Kept for reference or older existing setups.

• Bash/pre-4.5/qBitTorrent-Cleanup.sh

  • Legacy Bash script for qBitTorrent versions before 4.5.
  • Kept only because older qBitTorrent log formats differ.

Recommendation

Use the Python version unless you specifically need one of the legacy Bash scripts.

The Bash scripts are archived for historical compatibility. They still rely on hard-coded paths and older assumptions, so they should be treated as legacy tools rather than the preferred deployment path.

Background

When qBitTorrent is used with auto-unpacking tools, it can leave behind extracted folders after a torrent is removed. This repository provides cleanup scripts to remove those orphaned directories.

Python Version

The Python version is the main implementation and the one the Docker setup runs.

Features

• Direct qBitTorrent WebUI API access
• Docker-friendly deployment
• Dry-run support
• Daemon or cron-style execution
• Safer directory matching based on qBitTorrent-reported paths
• Guardrails for excluded directory names, minimum directory age, and empty-client protection

Requirements

• Docker
• Docker Compose
• qBitTorrent with WebUI enabled

Quick Start

1. Clone the repository:

git clone https://github.com/Jarsky/qBitTorrent-Cleanup-Script
cd qBitTorrent-Cleanup-Script

2. Create your environment file:

cp env.example.env .env

3. Update .env with your qBitTorrent settings.

4. Update docker-compose.yml so your real download directory is mounted to /downloads.

5. Start the container:

docker-compose up -d

Configuration

The following environment variables can be configured in .env:

Variable	Default	Description
QB_HOST	localhost	qBitTorrent WebUI host
QB_PORT	8080	qBitTorrent WebUI port
QB_USERNAME	admin	qBitTorrent WebUI username
QB_PASSWORD	adminadmin	qBitTorrent WebUI password
QB_DOWNLOAD_PATH	/downloads	Path to the qBitTorrent download directory inside the runtime
LOG_FILE	/logs/qbt-cleanup.log	Path to log file
DRY_RUN	false	Set to true to test without making changes
EXCLUDED_DIR_NAMES	.stfolder,@eaDir,lost+found	Comma-separated top-level directories that should never be deleted
MIN_DIR_AGE_SECONDS	0	Skip deleting directories newer than this many seconds
ALLOW_EMPTY_CLIENT	false	If false, cleanup is skipped when qBitTorrent reports zero torrents
EXECUTION_MODE	daemon	Run mode: daemon or cron
SLEEP_INTERVAL	14400	Time in seconds between runs when in daemon mode
CRON_SCHEDULE	0 */4 * * *	Cron expression used when EXECUTION_MODE=cron

How the Python Version Works

1. Connects to the qBitTorrent WebUI API.
2. Retrieves the current torrent list.
3. Protects active top-level download directories using qBitTorrent-reported paths.
4. Scans the configured download root for top-level directories.
5. Deletes directories that are no longer in use, while respecting the configured safety guardrails.

Safety Notes

• The Python cleanup logic only evaluates top-level directories inside QB_DOWNLOAD_PATH.
• A dedicated per-torrent folder layout is strongly recommended.
• Cleanup is skipped by default if qBitTorrent reports zero torrents.
• Use DRY_RUN=true first whenever you change download paths or exclusions.

Running Without Docker

If you want to run the Python version directly:

1. Install Python 3.7+.
2. Install dependencies:

pip install -r requirements.txt

3. Run the script:

python Python/qBitTorrent-Cleanup.py

Command Line Options

• --dry-run
• --daemon
• --interval 3600
• --run-once

Legacy Bash Versions

The Bash scripts are kept for legacy purposes only.

Bash/pre-4.5/qBitTorrent-Cleanup.sh

• For qBitTorrent versions before 4.5.
• Relies on the older log message format such as Error: Directory not empty.

Bash/4.5+/qBitTorrent-Cleanup.sh

• For qBitTorrent 4.5 and newer.
• Includes both -legacy log parsing and -run mode via qbittorrent-cli.

Bash Notes

• The Bash scripts are not the recommended path for new users.
• They use hard-coded paths and older operational assumptions.
• If you still use them, run them in test mode first.

Why Python Is Preferred

• No dependency on qBitTorrent log parsing for normal operation
• Safer matching against active torrent paths
• Better error handling
• Easier Docker deployment
• Clearer configuration via environment variables