transmission-cleaner 1.1.1

Transmission maintenance tool for managing torrents by hardlinks, errors, and orphaned files

Transmission Cleaner

A comprehensive CLI tool for maintaining your Transmission torrents.

• 🔗 Find torrents without hardlinks - Identify torrents that aren't hardlinked to media libraries (Sonarr, Radarr, etc.)
• ‼️ Manage errored torrents - Find and clean up torrents with errors (unregistered, tracker issues, etc.)
• 🗑️ Detect orphaned files - Discover files in your download directories that aren't tracked by any torrent
• 🛡️ Protections - Checks for cross-seeding and HNR violations for private torrents (PTP, BTN, BHD, TVCUK)

Support

Unit tests ran against all of the following combinations

• Python versions: 3.10 up to 3.14
• OS: macOS, Linux, windows

Installation

Quick Install (Recommended)

If you haven't yet, install uv (curl -LsSf https://astral.sh/uv/install.sh | sh). It's a massive painkiller for the python management headache.

# Using uv (recommended for CLI tools)
uv tool install transmission-cleaner

# Or from source
git clone https://github.com/flying-sausages/transmission-cleaner.git
cd transmission-cleaner
uv tool install .

Usage

The tool is organized into subcommands, each targeting a specific maintenance task:

transmission-cleaner <command> [options]

Commands Overview

• hardlinks - Find and manage torrents without hardlinks to other files
• errors - Find and manage torrents with error status
• orphans - Find and manage files not tracked by any torrent

All commands require authentication to the transmission RPC server. You can either:

• Use default RPC settings for local installs and use the --username and --password settings
• Point to your local daemon's config and supply a --password,
• Override the RPC defaults

Run any command with --help for detailed options.

1. Hardlinks Command

Find torrents whose files don't have hardlinks elsewhere on your system. Perfect for cleaning up after media that's been deleted from your library.

# List torrents without hardlinks
transmission-cleaner hardlinks --username USER --password PASSWORD

Options:

• -d, --directory - Filter by download directory (substring match)
• -t, --tracker - Filter by announce URL (substring match)
• --min-days - Minimum days of active seeding (default: 7)
• --action - Action to perform: list (default), interactive, delete (with data), remove (torrent only)
• --skip-hnr - Skip HNR check for private torrents (allows deletion even if HNR would be violated)

2. Errors Command

Find and manage torrents with error status, such as unregistered torrents or tracker failures. Includes cross-seed detection to prevent accidental data loss.

# List all torrents with errors
transmission-cleaner errors --username USER --password PASSWORD

Options:

• -d, --directory - Filter by download directory (substring match)
• -t, --tracker - Filter by announce URL (substring match)
• --min-days - Minimum days of active seeding (default: 7)
• --error-pattern - Filter by error message pattern (e.g., "Unregistered")
• --skip-cross-seed - Skip cross-seed detection (allows data deletion even if cross-seeded)
• --action - Action to perform: list (default), interactive, delete (with data), remove (torrent only)
• --skip-hnr - Skip HNR check for private torrents (allows deletion even if HNR would be violated)

Cross-Seed Protection: By default, the errors command checks if torrent data is shared with other active torrents. If cross-seeding is detected, the delete action will only remove the torrent entry, protecting the shared data.

3. Orphans Command

Find files in your download directories that aren't tracked by any torrent. Useful for cleaning up leftover files from deleted torrents or manual downloads.

# List orphaned files in a directory
transmission-cleaner orphans \
--username USER --password PASSWORD \
--directory /path/to/downloads

Options:

• -d, --directory - Directory to scan (required)
• --include-hidden - Include hidden files (files starting with .)
• --skip-disjoint - Skip validation that directory is within Transmission's download directory
• --action - Action to perform: list (default), interactive, delete

Safety Check: By default, the orphans command validates that the specified directory is within Transmission's base download directory. This prevents accidentally scanning and deleting files from unrelated directories. Use --skip-disjoint to bypass this check if you need to scan directories outside the Transmission download tree.

Note: The orphans scanner automatically excludes:

• Symlinks (to prevent scanning outside the target directory)
• System files (.DS_Store, Thumbs.db, etc.)
• .torrent files
• Hidden files (unless --include-hidden is specified)

Authentication Options

All commands support the same authentication options:

--settings-file PATH     # Path to Transmission settings.json file
--protocol {http,https}  # Protocol to use (default: http)
--username USERNAME      # Transmission username
--password PASSWORD      # Transmission password (required)
--host HOST             # Transmission host (default: 127.0.0.1)
--port PORT             # Transmission port (default: 9091)
--rpc-path PATH             # Transmission RPC path (default: /transmission/rpc)

Example with settings file:

transmission-cleaner hardlinks \
  --settings-file ~/.config/transmission-daemon/settings.json \
  --password YOUR_PASSWORD

Arrs Setup Suggestion

For automated cleanup with Sonarr/Radarr:

1. Have something (Plex/Maintainerr/etc.) automatically delete media
2. Set Unmonitor Deleted Episodes to True in your arr
3. In the arr's download client settings, set a Category value (e.g., "Sonarr" or "Radarr")
4. Test the tool manually:

   transmission-cleaner hardlinks \
     --settings-file ~/.config/transmission-daemon/settings.json \
     --password YOUR_PASSWORD \
     --directory Sonarr \
     --action list
   

5. Add to crontab for daily cleanup at 3am:

   0 3 * * * transmission-cleaner hardlinks --settings-file ~/.config/transmission-daemon/settings.json --password YOUR_PASSWORD --directory Sonarr --action delete >> /var/log/transmission-cleaner.log 2>&1
   

Action Modes

All commands support these action modes:

• list (default) - Display matching items without making changes
• interactive - Prompt for confirmation before each action
• delete - Remove torrent with data from disk
• remove - Remove torrent from client only (keeps data)

Short forms: l for list, i for interactive, d for delete, r for remove

Safety Notes

• Always test with --action list first to see what would be affected
• Use interactive mode when unsure about automatic removal
• Backup your data before performing bulk deletions
• Cross-seed protection in the errors command helps prevent data loss for shared files
• The tool requires direct filesystem access to check hardlinks and scan directories
• Orphans scanner excludes symlinks to prevent scanning outside target directories

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development

# Set up the project
uv sync

# Run linting
ruff check .

# Run type checking
basedpyright

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov

HNRs

There's a template for HNR checks for private trackers. You can consult the README.md in that directory for instructions on how to add new templates.