Skip to main content

Download Client

Configure download client connections for torrents. Cleanuparr supports the latest versions of the following download clients:

  • qBittorrent
  • Deluge
  • Transmission
  • µTorrent
  • rTorrent

Enable Download Client

Controls whether this download client instance is active and will be used by Cleanuparr for operations.

When Enabled:

  • Client will be available for slow, stalled and private tracker operations.
  • Health checks will monitor this client.

When Disabled:

  • Client will be ignored by all Cleanuparr operations.
  • No health checks will be performed.

Client Name

A descriptive name to identify this download client instance in the Cleanuparr interface.

Client Type

Specifies which download client software this configuration connects to.

Connection Settings

Client Host

The complete URL to access your download client's web interface.

Format: protocol://hostname:port

Examples:

  • http://localhost:8080 (local qBittorrent)
  • https://seedbox.example.com:8080 (remote qBittorrent with SSL)
  • http://192.168.1.100:8112 (local network Deluge)
  • http://transmission.lan:9091 (local Transmission)
  • http://localhost:8000/RPC2 (rTorrent via XMLRPC)

URL Base Path

URL path prefix if your download client runs behind a reverse proxy with a subpath.

When to Use:

  • Client accessed via reverse proxy (Nginx, Apache, Traefik).
  • Client uses non-root URL path.
  • Multiple services share same domain/port.

Examples:

  • qbittorrent → Full URL: http://domain.com/qbittorrent
  • downloads/deluge → Full URL: http://domain.com/downloads/deluge
  • transmission → Full URL: http://domain.com/transmission

External URL

Optional external URL used in notification messages instead of the internal host URL. This is useful for Docker users where internal container URLs (e.g., http://qbittorrent:8080) are not reachable from outside the Docker network.

When to Use:

  • Running Cleanuparr in Docker with internal container networking.
  • Notification links need to be clickable from your browser or phone.
  • Internal URLs differ from externally-accessible URLs.

Examples:

  • https://qbit.mydomain.com
  • http://192.168.1.100:8080

If not set, the internal host URL will be used in notifications.

Authentication

Username

Username for download client authentication if required.

Password

Password for download client authentication.

Path Mapping

Download Directory Source and Target

Some Cleanuparr features need to read the actual files on disk — unlinked download handling, orphaned files, and deleting source files. The download client and Cleanuparr do not always see those files at the same path. This is common in Docker, where each container mounts the same folder under a different path. Path mapping tells Cleanuparr how to translate the path the client reports into the path Cleanuparr can actually reach.

  • Download Directory Source — the path exactly as the download client reports it (e.g. /downloads).
  • Download Directory Target — the path where Cleanuparr actually finds those same files (e.g. /mnt/data/downloads). Cleanuparr replaces the source prefix with the target prefix.

Leave both fields blank if the download client and Cleanuparr already see the files at the same path (no path translation needed).

Docker example:

In a typical Docker Compose setup, each container has its own view of the filesystem. Two download clients may each report paths starting with /downloads, even though their files live in different host folders. Cleanuparr mounts those host folders under different paths, so it needs a mapping per client to 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-deluge:/downloads-deluge # Cleanuparr sees /downloads-deluge

Both clients report paths under the same /downloads prefix, but Cleanuparr mounts each host folder under a different path, so it needs the translation per client:

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

    • Download Directory Source: /downloads
    • Download Directory Target: /downloads-qbit

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

    • Download Directory Source: /downloads
    • Download Directory Target: /downloads-deluge