Skip to main content

Deluge Web API Client

PyPI Version Python Versions License Quality PyPI Ruff codecov

Python HTTP client implementation for Deluge

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")

Error Handling

Every Deluge or network failure raises DelugeWebClientError or one of its subclasses, so catching the base class is always enough:

DelugeWebClientError
├── DelugeWebClientConnectionError   # unreachable host, DNS, TLS, proxy
├── DelugeWebClientTimeoutError      # connect / read timeout
├── DelugeWebClientHTTPError         # non-2xx (.status_code, .reason)
├── DelugeWebClientRPCError          # Deluge reported an error (.method, .error_class, .info_hash)
└── DelugeWebClientDecodeError       # response body was not a JSON object
from deluge_web_client import (
    DelugeWebClient,
    DelugeWebClientConnectionError,
    DelugeWebClientError,
    DelugeWebClientRPCError,
)

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

try:
    client.login()
except DelugeWebClientConnectionError:
    print("no Deluge Web UI at that URL")
except DelugeWebClientRPCError as error:
    print(f"Deluge rejected the call: {error.method}")
except DelugeWebClientError as error:
    # catches everything above, including anything added in the future
    print(f"something went wrong: {error}")

The underlying niquests exception is preserved as __cause__ on connection and timeout errors if you need the transport level detail.

Two exceptions are deliberately not wrapped, because they signal a bad argument rather than a Deluge failure:

  • ValueError — the url passed to DelugeWebClient is not an absolute HTTP/HTTPS URL, or contains a fragment.
  • OSError / FileNotFoundError — a torrent file passed to upload_torrent cannot be read.

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.

Metadata

Release files for deluge-web-client 2.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for deluge-web-client 2.1.2
File Size Uploaded Provenance Actions
deluge_web_client-2.1.2.tar.gz 28.5 kB With provenance Details for deluge_web_client-2.1.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for deluge-web-client 2.1.2
File Interpreter ABI Platform Actions
deluge_web_client-2.1.2-py3-none-any.whl Python 3 none any Details for deluge_web_client-2.1.2-py3-none-any.whl

Total release size: 45.2 kB

Release files / deluge_web_client-2.1.2.tar.gz

Download URL deluge_web_client-2.1.2.tar.gz
Size 28.5 kB
Tags Source
SHA-256 checksum
How to use checksums
588328576213096d5a6920fa31d63abd4eb6366ff300eddca854a81fc9d21b03
BLAKE2b-256 checksum
How to use checksums
31a15f989127a56470020e863f6b940f5f8628418e769f276190e9feaa7484a8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / deluge_web_client-2.1.2-py3-none-any.whl

Download URL deluge_web_client-2.1.2-py3-none-any.whl
Size 16.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0270008387dcc8456189e6d9d04b1ec76ccd25be00d8d997e87667dc632d9eaa
BLAKE2b-256 checksum
How to use checksums
a33480456550a8871f47a8270871b2aa936b024ece9fe403294eb469941e2a71
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for deluge-web-client 2.1.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for deluge_web_client-2.1.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page