Skip to main content

Download Cleaner

The Download Cleaner automatically removes downloads from your download client after they have finished seeding according to configurable rules. This helps manage disk space and maintain optimal seeding ratios.

Important

These settings need a download client to be configured.

Enable Download Cleaner

When enabled, the Download Cleaner will run according to the configured schedule to automatically clean completed downloads from your download client.

Scheduling Mode

Choose how to configure the Download Cleaner schedule:

  • Basic: Simple interval-based scheduling (every X minutes/hours/seconds)
  • Advanced: Full cron expression control for complex schedules

Cron Expression

Enter a valid Quartz.NET cron expression to control when the Download Cleaner runs. The example above runs every hour.

Common Cron Examples:

  • 0 0/5 * ? * * * - Every 5 minutes
  • 0 0 * ? * * * - Every hour
  • 0 0 */6 ? * * * - Every 6 hours

Ignored Downloads

Downloads matching these patterns will be ignored by Download Cleaner. Patterns can match any of these:

  • torrent hash
  • qBittorrent tag or category
  • Deluge label
  • Transmission category (last directory from the save location)
  • µTorrent label
  • torrent tracker domain

Examples:

fa800a7d7c443a2c3561d1f8f393c089036dade1
tv-sonarr
qbit-tag
mytracker.com

Seeding Rules

Seeding rules define the cleanup criteria for downloads in your download client. Each rule specifies which downloads it applies to (by category, tracker, tags, and privacy type) and when they should be removed based on ratio and time limits. Rules are evaluated in priority order — the first matching rule wins.

Note

A download is cleaned when both Max Ratio and Min Seed Time are reached, OR when Max Seed Time is reached regardless of ratio. If Min Seeders is configured, the download is kept until that minimum seeder count is also met.

Important

Both Max Ratio and Max Seed Time cannot be disabled (-1) at the same time. At least one cleanup condition must be configured.

Rule Name

A human-readable label for this seeding rule. This is a display name only and does not affect rule matching.

Examples:

  • TV shows
  • Movies - private trackers
  • Music long seed

Categories

One or more download client categories this rule applies to. A torrent matches if its category matches any entry in the list (case-insensitive). At least one category must be specified.

Examples:

  • tv-sonarr
  • radarr
  • lidarr

Tracker Patterns

Tracker domain suffixes used to filter which torrents this rule applies to. A torrent matches if any of its tracker domains end with one of these patterns (case-insensitive). Leave empty to match torrents from any tracker.

Examples:

  • tracker.example.com — matches https://tracker.example.com/announce
  • private.org — matches any tracker whose domain ends with private.org

Tags (Any)

Torrent must have at least one of these tags or labels. Leave empty to skip tag filtering.

Supported by qBittorrent tags and Transmission labels.

Tags (All)

Torrent must have all of these tags or labels. Leave empty to skip tag filtering.

Supported by qBittorrent tags and Transmission labels.

Privacy Type

Controls which torrent types this rule applies to:

  • Public: Rule only applies to public torrents
  • Private: Rule only applies to private torrents
  • Both: Rule applies to all torrents (default)

You can create multiple rules for the same category with different privacy types to apply different cleanup settings to public and private torrents.

Warning

Setting privacy type to Private or Both means private torrents matching this rule will be permanently deleted, potentially affecting your private tracker account by receiving H&R if the seeding requirements are not met.

Max Ratio

Maximum ratio to seed before considering the download for removal. Set to -1 to disable ratio-based cleanup.

Min Seed Time

Minimum time in hours to seed before removing a download that has reached the max ratio. Set to 0 to disable minimum time requirements.

Max Seed Time

Maximum time in hours to seed before removing a download regardless of ratio. Set to -1 to disable time-based cleanup.

Min Seeders

Minimum number of seeders required before removing a download. Set to 0 to disable seeder-count protection.

When enabled, this acts as a deletion guard: downloads that have reached their ratio or seed-time cleanup condition are still kept if the reported seeder count is below this value.

If the selected download client cannot report a seeder count for a download, the download is kept instead of being deleted.

Supported by qBittorrent, Deluge, Transmission, and µTorrent.

Delete Source Files

When enabled, the source files will be deleted from disk when the download is removed from the download client. When disabled, only the torrent entry is removed while preserving the underlying files.

Orphaned Files

The Orphaned Files feature scans configured directories for files and directories no longer tracked by any active torrent and moves them to a dedicated orphaned directory. It runs as part of the Download Cleaner job and shares its schedule. Supported for all download clients: qBittorrent, Transmission, Deluge, rTorrent, and uTorrent.

All Orphaned Files settings are configured per download client in the Orphaned Files accordion inside the per-client section.

Exclude Patterns

Glob patterns for file or directory names that should never be considered orphaned, even if no active torrent claims them. Matching is case-insensitive and applied to the entry name only, not the full path.

Examples:

*.nfo
*.txt
.DS_Store
Thumbs.db
Note

Use * as a wildcard for any characters. For example, *.nfo matches any file ending in .nfo regardless of its location inside the scan directory.

Min File Age

Minimum age in hours a file or directory must have before it can be considered orphaned. This protects files that are actively being downloaded or have just finished — they may not yet be registered as a torrent save path.

Defaults to 24 hours. Set to 0 to disable the age check.

Example: Set to 1 to skip any entry modified less than an hour ago.

Purge Orphaned After

Number of hours after which entries in the Orphaned Directory are permanently deleted. Leave empty to keep orphaned files indefinitely.

Example: Set to 720 to automatically purge orphaned files older than 30 days.

Warning

Files deleted by this option are permanently removed from disk. Review the contents of your Orphaned Directory before enabling this setting.

Enabled (per client)

Enable orphaned files scanning for this specific download client. The download client must also be enabled in Download Client settings.

Scan Directories

Absolute paths to scan for orphaned files for this download client. Each top-level entry inside these directories is checked against the save paths of all active torrents across all enabled clients. If no active torrent claims an entry, it is considered orphaned.

Examples:

/data/downloads/completed
/data/downloads/cross-seed
Important

Each path must be accessible by Cleanuparr. If running in Docker, make sure to mount the directories accordingly.

Important

Scan directories must not overlap (be equal to, a parent of, or a subdirectory of) the scan directories or orphaned directory of any other download client. Cleanuparr enforces this at save time to prevent cross-client false positives.

Orphaned Directory

The directory where orphaned files and directories are moved for this download client. Required when the orphaned files cleanup is enabled.

Example:

/data/downloads/orphaned
Note

The orphaned directory itself is never scanned for orphans. If the destination already contains an entry with the same name, a timestamp suffix is appended automatically to avoid collisions.

Unlinked Download Settings

Settings for managing downloads that no longer have hardlinks to media files (indicating they may no longer be needed by the *arr applications).

Enable Unlinked Download Handling

Enable management of downloads that have no hardlinks remaining. This helps identify downloads that are no longer needed by your *arr applications.

Important

If you are using Docker, make sure to mount the downloads directory the same way it is mounted for the download client. If your download client's download directory is /downloads, it should be the same for Cleanuparr.

Target Category

Category to move unlinked downloads to. You must create a seeding rule for this category if you want the downloads to eventually be removed.

Use Tag

When enabled, marks unlinked downloads with a tag instead of changing their category, preserving the original category. Supported by qBittorrent (tags) and Transmission (labels); not available for other clients.

Download Directory (Source) and Local Directory (Target)

The path prefix as reported by the download client (e.g. /downloads). Used for path mapping when the download client's internal paths differ from the paths accessible to Cleanuparr — common in Docker setups where volume mount paths differ between containers. Leave blank if no path translation is needed.


Docker example:

In a typical Docker Compose setup, each container has its own view of the filesystem. Download clients may each have their own host directory but both report paths starting with /downloads. Since Cleanuparr mounts those directories under different paths, you need to configure the mapping per client so Cleanuparr can locate the actual files.

services:
  qbittorrent:
    image: ...
    ...
    volumes:
      - /host/data/downloads-qbit:/downloads        # qBittorrent sees /downloads

  deluge:
    image: ...
    ...
    volumes:
      - /host/data/downloads-deluge:/downloads      # Deluge sees /downloads

  cleanuparr:
    image: ghcr.io/cleanuparr/cleanuparr
    ...
    volumes:
      - /host/data/downloads-qbit:/downloads-qbit   # Cleanuparr sees /downloads-qbit
      - /host/data/downloads-qbit:/downloads-deluge # Cleanuparr sees /downloads-deluge

Both download clients store files in separate host directories but report paths under the same /downloads prefix. Cleanuparr mounts each host directory under a different path, so it needs to know the translation per client:

  • qBittorrent reports /downloads/movie.mkv while Cleanuparr finds it at /downloads-qbit/movie.mkv

    • Download Directory (Source): /downloads
    • Local Directory (Target): /downloads-qbit

  • Deluge reports /downloads/movie.mkv while Cleanuparr finds it at /downloads-deluge/movie.mkv

    • Download Directory (Source): /downloads
    • Local Directory (Target): /downloads-deluge

Ignored Root Directory

Root directories to ignore when checking for unlinked downloads. Multiple paths can be added. Useful for cross-seed setups where you want to ignore hardlinks (even though a movie is not in Radarr anymore, it can have hardlinks from cross-seed).

/data
├── downloads
│   ├── torrents
│   └── cross-seed
├── movies
└── shows

For the example above, the ignored root directory should be set to /data/downloads.

Unlinked Categories

Categories to check for unlinked downloads. Only downloads in these categories will be checked for missing hardlinks.

Dead Torrents

A dead torrent is one whose tracker reports no seeders for a prolonged period — typically because it was removed from the tracker, or the tracker host itself is gone — so it can never reach a ratio or seed-time threshold. Instead of deleting such torrents, this feature moves them to a target category (or adds a tag/label) so you can decide what to do next via a seeding rule for that category/tag. It runs as part of the Download Cleaner job. Configured per download client in the Dead Torrents accordion.

Note

A torrent is considered dead on a run when the client reports no seeders — a count of 0, an unknown count (e.g. qBittorrent's -1), or no count at all because the tracker is unreachable. It is only moved after it has been dead for the configured number of consecutive runs (the strike count), and strikes reset to zero as soon as the client reports seeders again. Supported for qBittorrent, Transmission, Deluge, and µTorrent — not rTorrent, which does not report a seeder count.

Enable Dead Torrent Handling

When enabled, torrents in the configured categories that report no seeders for the configured number of consecutive runs are moved to the target category (or tagged). Create a seeding rule for that category/tag to control whether and when they are removed.

Dead Torrent Target Category

The category a dead torrent is moved to (or the tag/label added when Use Tag is enabled). Create a seeding rule for this category/tag to manage the moved torrents.

Dead Torrent Use Tag

When enabled, adds a tag/label instead of changing the category, preserving the original category. Supported by qBittorrent (tags) and Transmission (labels). For Transmission, changing the category (with this option off) moves the files on disk, whereas using a label does not.

Dead Torrent Strikes

The number of consecutive runs a torrent must report no seeders before it is moved. Minimum is 3. Strikes reset to zero as soon as seeders are found again.

Set this high enough to ride out tracker downtime so a temporarily-unreachable tracker isn't mistaken for a dead one. Choose it together with the Download Cleaner schedule — with an hourly schedule, 24 ≈ one day and 168 ≈ one week of being continuously dead.

Dead Torrent Categories

Source categories to scan for dead torrents. Only downloads in these categories are checked. The target category must not be one of these.