class platypush.plugins.rtorrent.RtorrentPlugin(url: str, poll_seconds: float = 5.0, download_dir: str = '~/.rtorrent/watch', **kwargs)[source]

Plugin to interact search, download and manage torrents through RTorrent. The usage of this plugin is advised over platypush.plugins.torrent.TorrentPlugin, as RTorrent is a more flexible and optimized solution for downloading and managing torrents compared to the Platypush native plugin.


  • Install rtorrent on your system - on Debian/Ubuntu/Raspbian:

    apt-get install rtorrent
  • Configure the rtorrent XML/RPC interface, usually by adding the following lines to your ~/.rtorrent.rc:

    # Enable XML/RPC
    scgi_local = /home/user/.rpc.socket
  • Use a web server to bridge the RPC interface exposed by RTorrent over HTTP. Some configuration examples are available here. I usually use lighttpd because it’s easy to configure and it comes with a built-in SCGI module. Install the server e.g. using apt:

    apt-get install lighttpd
  • Create a base configuration file like this under e.g. ~/.config/rtorrent/lighttpd.conf:

    ### Base configuration
    server.modules = (
    # Make sure that all the directories exist.
    # server.document-root isn't really needed, but lighttpd
    # won't start if it doesn't find a document root.
    server.document-root        = "/home/user/.local/share/rtorrent/html"
    server.upload-dirs          = ( "/home/user/.cache/uploads" )
    server.errorlog             = "/home/user/.local/log/rtorrent/error.log"
    server.pid-file             = "/home/user/.local/run/lighttpd.pid"
    server.username             = "your-user"
    server.groupname            = "your-group"
    server.port                 = 5000
    index-file.names            = ( "index.html" )
    ### Configure the RTorrent XML/RPC endpoint
    server.modules += ( "mod_scgi" )
    scgi.server = (
        # Bind an endpoint called /RPC2 to your local interface
        "/RPC2" =>
          ( "" =>
              # Read from the RTorrent XML/RPC socket
              "socket" => "/home/user/.rpc.socket",
              "check-local" => "disable",
              "disable-time" => 0,  # don't disable scgi if connection fails
  • Start the HTTP service, and optionally enable it as a system/user service:

    lighttpd -f ~/.config/rtorrent/lighttpd.conf
  • Start RTorrent and check that the XML/RPC interface works:

    $ xmlrpc localhost:8000 system.listMethods
    # Should return a list with all the methods exposed by RTorrent.
    $ xmlrpc localhost:5000 download_list
    Array of 0 items:
  • It is advised to let the RTorrent instance run in e.g. screen or tmux on the server machine - it is more reliable than letting the plugin start/stop the instance, and you have an easy CLI interface to attach to manage/monitor your torrents.

  • In this example, the URL to configure in the plugin would be http://localhost:5000/RPC2.


__init__(url: str, poll_seconds: float = 5.0, download_dir: str = '~/.rtorrent/watch', **kwargs)[source]
  • url – HTTP URL that exposes the XML/RPC interface of RTorrent (e.g. http://localhost:5000/RPC2).

  • poll_seconds – How often the plugin will monitor for changes in the torrent state (default: 5 seconds).

  • download_dir – Directory where torrents and metadata files will be downloaded (default: ~/.rtorrent/watch).

download(torrent: str, is_media: bool = False, *_, **__)[source]

Download a torrent.

  • torrent

    Torrent to download. Supported formats:

    • Magnet URLs

    • Torrent URLs

    • Local torrent files

  • is_media – Set it to true if you’re downloading a media file that you’d like to stream as soon as the first chunks are available. If so, then the events and the status method will only include media files


The status of the torrent.

download_torrent_file(torrent: str) str[source]

Download a torrent link to torrent_files_dir.


torrent – Torrent URL, magnet link or local file.


Path to the locally downloaded .torrent file.

execute(method: str, *args, **kwargs)[source]

Execute a raw command over the RTorrent RPC interface.

  • method – Method name.

  • args – Method arguments.

  • kwargs – Method keyword-arguments.


Anything returned by the RPC method.

list_methods() List[str][source]

The list of methods exposed by the RTorrent instance

open(torrent: str) dict[source]

Open a loaded torrent transfer.


torrent – Torrent hash.


The status of the torrent.

pause(torrent: str) dict[source]

Pause a torrent transfer.


torrent – Torrent hash.


The status of the torrent.


Terminate all the active transfers and quit the monitor.


Stop and remove a torrent transfer (without removing the downloaded files).


torrent – Torrent hash.

resume(torrent) dict[source]

Resume a torrent transfer.


torrent – Torrent hash.


The status of the torrent.

search(query, category=None, language=None, *args, **kwargs)

Perform a search of video torrents.

  • query (str) – Query string, video name or partial name

  • category (str or list) – Category to search. Supported types: “movies”, “tv”. Default: None (search all categories)

  • language (str) – Language code for the results - example: “en” (default: None, no filter)


Start monitoring the status of the RTorrent instance.

status(torrent: str = None) dict[source]

Get the status of the current transfers.


torrent – Torrent hash.


A dictionary:

  "HASH1234567890": {
    "hash": "HASH1234567890",
    "name": "Your torrent name",
    "save_path": "/home/user/Downloads/Your torrent name",
    "is_active": true,
    "is_open": true,
    "completed_bytes": 666894336,
    "download_rate": 451345,
    "is_multi_file": true,
    "remaining_bytes": 1482827011,
    "size_bytes": 2149721347,
    "load_date": "2020-09-02T18:42:19",
    "peers": 0,
    "state": "paused",
    "start_date": "2020-09-02T18:42:19",
    "finish_date": null,
    "upload_rate": 143967,
    "progress": 31.0,
    "files": ["list", "of", "downloaded", "files"]

stop(torrent) dict[source]

Stop a torrent transfer.


torrent – Torrent hash.


The status of the torrent.


Stop monitoring the status of the RTorrent instance.