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

Categories define the cleanup rules for different types of downloads. Each category specifies when downloads should be removed based on ratio and time limits.

💡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.

⚠️Important

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

Category Name

The name of the download client category to apply these rules to. Must match the category name exactly as configured in your download client.

Examples:

  • tv-sonarr
  • radarr
  • lidarr

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.

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.

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, uses a tag instead of category for marking unlinked downloads (qBittorrent only).

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.