qBittorrent Web API Client

Introduction

github ci codecov

pypi pypi versions pypi downloads

Python client implementation for qBittorrent Web API.

Currently supports qBittorrent v4.6.5 (Web API v2.9.3) released on May 26, 2024.

Features

  • The entire qBittorrent Web API is implemented.

  • qBittorrent version checking for an endpoint’s existence/features is automatically handled.

  • If the authentication cookie expires, a new one is automatically requested in line with any API call.

Installation

  • Install via pip from PyPI:

python -m pip install qbittorrent-api
  • Install a specific release (e.g. v2024.3.60):

python -m pip install qbittorrent-api==2024.3.60
  • Install direct from main:

pip install git+https://github.com/rmartin16/qbittorrent-api.git@main#egg=qbittorrent-api
  • Enable WebUI in qBittorrent: Tools -> Preferences -> Web UI

  • If the Web API will be exposed to the Internet, follow the recommendations.

Getting Started

import qbittorrentapi

# instantiate a Client using the appropriate WebUI configuration
conn_info = dict(
    host="localhost",
    port=8080,
    username="admin",
    password="adminadmin",
)
qbt_client = qbittorrentapi.Client(**conn_info)

# the Client will automatically acquire/maintain a logged-in state
# in line with any request. therefore, this is not strictly necessary;
# however, you may want to test the provided login credentials.
try:
    qbt_client.auth_log_in()
except qbittorrentapi.LoginFailed as e:
    print(e)

# if the Client will not be long-lived or many Clients may be created
# in a relatively short amount of time, be sure to log out:
qbt_client.auth_log_out()

# or use a context manager:
with qbittorrentapi.Client(**conn_info) as qbt_client:
    if qbt_client.torrents_add(urls="...") != "Ok.":
        raise Exception("Failed to add torrent.")

# display qBittorrent info
print(f"qBittorrent: {qbt_client.app.version}")
print(f"qBittorrent Web API: {qbt_client.app.web_api_version}")
for k, v in qbt_client.app.build_info.items():
    print(f"{k}: {v}")

# retrieve and show all torrents
for torrent in qbt_client.torrents_info():
    print(f"{torrent.hash[-6:]}: {torrent.name} ({torrent.state})")

# stop all torrents
qbt_client.torrents.stop.all()

Usage

First, the Web API endpoints are organized in to eight namespaces.

  • Authentication (auth)

  • Application (app)

  • Log (log)

  • Sync (sync)

  • Transfer (transfer)

  • Torrent Management (torrents)

  • RSS (rss)

  • Search (search)

Second, this client has two modes of interaction with the qBittorrent Web API.

Each Web API endpoint is implemented one-to-one as a method of the instantiated client.

import qbittorrentapi
qbt_client = qbittorrentapi.Client(host='localhost:8080', username='admin', password='adminadmin')
qbt_client.app_version()
qbt_client.rss_rules()
qbt_client.torrents_info()
qbt_client.torrents_resume(torrent_hashes='...')
# and so on

However, a more robust interface to the endpoints is available via each namespace. This is intended to provide a more seamless and intuitive interface to the Web API.

import qbittorrentapi
qbt_client = qbittorrentapi.Client(host='localhost:8080', username='admin', password='adminadmin')
# changing a preference
is_dht_enabled = qbt_client.app.preferences.dht
qbt_client.app.preferences = dict(dht=not is_dht_enabled)
# stopping all torrents
qbt_client.torrents.stop.all()
# retrieve different views of the log
qbt_client.log.main.warning()
qbt_client.log.main.normal()

Finally, some of the objects returned by the client support methods of their own. This is most pronounced for torrents themselves.

import qbittorrentapi
qbt_client = qbittorrentapi.Client(host='localhost:8080', username='admin', password='adminadmin')

for torrent in qbt_client.torrents.info.active():
    torrent.set_location(location='/home/user/torrents/')
    torrent.reannounce()
    torrent.upload_limit = -1