User Guide and API Reference available on Read the Docs.

Features

• Provides access to the majority of Web API methods as well as key core functionalities through RPC. For more details, see the official Web API Documentation and RPC API Documentation.

• Allows you to use direct http connections, allowing access via reverse proxy or any direct url.

Installation

Install via pip from PyPI:

python -m pip install deluge-web-client
# or
poetry add deluge-web-client
# or
uv add deluge-web-client

Getting Started

Before getting started, ensure that you have a running instance of Deluge with the WebUI enabled. You will also need to have a user set up for authentication. For guidance on setting up the WebUI, visit the Deluge setup guide. Another good tutorial is Trash-Guides basic setup.

Basic Usage

from deluge_web_client import DelugeWebClient, TorrentOptions

# instantiate a client
client = DelugeWebClient(url="https://site.net/deluge", password="example_password")

# login
# once logged in the `client` will maintain the logged in state as long as you don't call
# client.disconnect()
client.login()

# uploading a torrent
# 1) define your torrent options (what ever you don't set here will utilize Deluge defaults)
torrent_options = TorrentOptions(
    add_paused=True,
    auto_managed=True,
)
# 2) upload the torrent and capture the returned output
upload = client.upload_torrent(
    torrent_path="filepath.torrent",
    torrent_options=torrent_options,
)
# this will return a `Response` object
print(upload)
# Response(result="<torrent-id>", error=None, message="Torrent added successfully")

# retrieve and show all torrents
all_torrents = client.get_torrents_status()

# pause torrent (pass torrent hash)
pause_torrent = client.pause_torrent("0407326f9d74629d299b525bd5f9b5dd583xxxx")

# remove torrent
remove_torrent = client.remove_torrent("0407326f9d74629d299b525bd5f9b5dd583xxxx")

Context Manager

from deluge_web_client import DelugeWebClient, TorrentOptions

# using a context manager automatically logs you in
with DelugeWebClient(url="https://site.net/deluge", password="example_password") as client:
    torrent_options = TorrentOptions(
        add_paused=True,
        auto_managed=True,
    )
    upload = client.upload_torrent(
        torrent_path="filepath.torrent",
        torrent_options=torrent_options,
    )
    print(upload)
    # Response(result="<torrent-id>", error=None, message="Torrent added successfully")

Notes

Calling client.disconnect() disconnects the Web UI session from its currently connected Deluge daemon. Call client.close_session() when you only need to release this client's HTTP resources.

Access RPC Directly

This package uses HTTP to connect to the Deluge client, relying on the Web API / JSON to handle these calls. It's fully capable of making all core calls to the Deluge backend. However, if you are looking for a package focused solely on RPC, consider deluge-client, which served as inspiration for this project alongside qbittorrent-api.