Skip to content
Switch branches/tags
Go to file

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


rtorrent-cleaner is a tool to clean up unnecessary files in rtorrent

styleci stable GitHub All Releases


  • php 5.5.9 and above (php 7.2 recommended)
  • php extension: php-cli, php-xmlrpc and php-mbstring


Install rtorrent-cleaner from phar file (recommended)

The preferred method of installation is to use the rtorrent-cleaner PHAR which can be downloaded from the most recent
Check GitHub Release.

Install rtorrent-cleaner from composer

Install rtorrent-cleaner in global

composer global require magicalex/rtorrent-cleaner

Install rtorrent-cleaner from DockerHub


docker run -it --rm magicalex/rtorrent-cleaner:latest

See the details here


Displaying help:

      _                            _          _
 _ __| |_ ___  _ __ _ __ ___ _ __ | |_    ___| | ___  __ _ _ __   ___ _ __
| '__| __/ _ \| '__| '__/ _ \ '_ \| __|  / __| |/ _ \/ _` | '_ \ / _ \ '__|
| |  | || (_) | |  | | |  __/ | | | |_  | (__| |  __/ (_| | | | |  __/ |
|_|   \__\___/|_|  |_|  \___|_| |_|\__|  \___|_|\___|\__,_|_| |_|\___|_|
rtorrent-cleaner version x.x.x

  command [options] [arguments]

  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  debug     Debug torrents
  help      Displays help for a command
  list      Lists commands
  mv        Move your unnecessary files in a specified folder
  report    Create a report on unnecessary files and missing files
  rm        Delete your unnecessary files in your download folder
  torrents  Delete torrents or redownload the missing files

Command report for create a report on unnecessary files and missing files:
(Configuration in your rtorrent.rc ex: network.scgi.open_port = localhost:5000)

rtorrent-cleaner report localhost:5000

Example with a socket (file rtorrent.rc network.scgi.open_local = /home/user/rpc.socket)

rtorrent-cleaner report /home/user/rpc.socket

You can log the console output in a file with the option --log (path: ./rtorrent-cleaner.log)
You can define a path (path: /var/log/rtorrent-cleaner.log)

rtorrent-cleaner report --log --
rtorrent-cleaner report -l /var/log/rtorrent-cleaner.log
rtorrent-cleaner report --log=/var/log/rtorrent-cleaner.log

Command rm for delete unnecessary files in your download folder:

rtorrent-cleaner rm
# delete without confirmation --assume-yes or -y
rtorrent-cleaner rm --assume-yes

Command mv for move unnecessary files in a specified folder (ex: /home/user/old) :

rtorrent-cleaner mv /home/user/old
# move without confirmation --assume-yes or -y
rtorrent-cleaner mv -y /home/user/old

Command torrents for delete torrents or redownload the missing files:

rtorrent-cleaner torrents

Option for the command mv, rm and report to ignore files: --exclude-files=

rtorrent-cleaner report --exclude-files=*.srt
rtorrent-cleaner report -f *.sub -f *.srt

The second example excludes all files .sub and .srt in the output

Option for the command mv, rm and report to ignore directories: --exclude-dirs=
The directories must be relative to directory default of rtorrent (directory.default in rtorrent.rc)

rtorrent-cleaner report --exclude-dirs=movies
rtorrent-cleaner report -d movies -d series

The second example excludes the movies and series directories

Usage with docker

Environment variables

Variable Description Type Default value
PHP_MEMORY_LIMIT Memory limit directive of php optional 128M
PHP_TIMEZONE Timezone directive of php optional UTC

Info: change <container_name> by the name of your container of rtorrent
Info: change </home/user/downloads> by your downloads folder
Info: change </data/downloads> by directory.default of rtorrent. See your file rtorrent.rc

Command for displaying help: rtorrent-cleaner

docker run -it --rm \
  -v </home/user/downloads>:</data/downloads> \
  --link <container_name>:rtorrent \

If you use your container with a network you can connect rtorrent-cleaner like this:
Info: change <network_name> by your network (you can list all the docker networks docker network ls)

docker run -it --rm \
  -v </home/user/downloads>:</data/downloads> \
  --network <network_name> \
  --link <container_name>:rtorrent \

Command for making a report: rtorrent-cleaner report rtorrent:5000

docker run -it --rm \
  -v </home/user/downloads>:</data/downloads> \
  --network <network_name> \
  --link <container_name>:rtorrent \
  magicalex/rtorrent-cleaner report rtorrent:5000

You can increase php memory limit if needed with PHP_MEMORY_LIMIT environment variable.
By default, the memory limit is 128M.

docker run -it --rm \
  -v </home/user/downloads>:</data/downloads> \
  --network <network_name> \
  --link <container_name>:rtorrent \

You can change the timezone with PHP_TIMEZONE environment variable.
By default, the timezone is UTC.

docker run -it --rm \
  -e PHP_TIMEZONE=Europe/Paris \
  -v </home/user/downloads>:</data/downloads> \
  --network <network_name> \
  --link <container_name>:rtorrent \

You can create a script for run rtorrent-cleaner with Docker

#!/usr/bin/env sh

docker run -it --rm \
  -v </home/user/downloads>:</data/downloads> \
  --network <network_name> \
  --link <container_name>:rtorrent \
  magicalex/rtorrent-cleaner $*

Or if you use a socket with rtorrent /run/php/.rtorrent.sock.

#!/usr/bin/env sh

docker run -it --rm \
  -v </home/user/downloads>:</data/downloads> \
  -v /run/php:/run/php \
  magicalex/rtorrent-cleaner $*
chmod +x /usr/local/bin/rtorrent-cleaner


rtorrent-cleaner report rtorrent:5000
rtorrent-cleaner rm rtorrent:5000
rtorrent-cleaner torrents rtorrent:5000
rtorrent-cleaner mv rtorrent:5000 /home/user/old

Or with a socket

rtorrent-cleaner report /run/php/.rtorrent.sock
rtorrent-cleaner rm /run/php/.rtorrent.sock
rtorrent-cleaner torrents /run/php/.rtorrent.sock
rtorrent-cleaner mv /run/php/.rtorrent.sock /home/user/old

Example with the docker image linuxserver/rutorrent

Configure your docker-compose.yml

version: "3"

    image: linuxserver/rutorrent:latest
    container_name: rutorrent
      - PUID=1000
      - PGID=1000
      - /path/to/rutorrent/config:/config
      - /path/to/rutorrent/downloads:/downloads
      - /run/php:/run/php
      - 80:80
      - 51413:51413
      - 6881:6881/udp
    restart: unless-stopped

Run linuxserver/rutorrent

docker-compose up -d

Create your rtorrent-cleaner script in /usr/local/bin folder

#!/usr/bin/env sh

docker run -it --rm \
  -e PHP_TIMEZONE=Europe/Paris \
  -v /path/to/rutorrent/downloads:/downloads \
  -v /run/php:/run/php \
  magicalex/rtorrent-cleaner $*

After this step you can run rtorrent-cleaner

chmod +x /usr/local/bin/rtorrent-cleaner
rtorrent-cleaner report /run/php/.rtorrent.sock

Build docker image

docker build -t magicalex/rtorrent-cleaner:latest

Build Phar Archive (rtorrent-cleaner.phar)

To build the archive phar, php 7.2 and php-phar extension is required.

git clone
cd rtorrent-cleaner
composer build


rtorrent-cleaner is released under the MIT License.