Registry / http-networking / qbittorrent-api

qbittorrent-api

JSON →
library2026.6.0pypypi✓ verified 87d ago

qbittorrent-api is a Python client library for interacting with the qBittorrent v4.1+ Web API. It provides a programmatic interface to manage torrents, retrieve application status, and control various aspects of the qBittorrent client. The library releases frequently, often mirroring updates in qBittorrent server versions or adding new API features, with the current version being 2025.11.1.

pip install qbittorrent-api
INSTALL
IMPORT
SIG · QBITTORRENT-API
Q
qbittorrent-api
http-networkingpythonv2026.6.0
Install
2.3s avg
Import
632ms
Disk
21MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v2026.6.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.659s · 22.5MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.3s · import 0.605s · 23MB
21MB installed
● package 21MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
from qbittorrentapi import Client
from qbittorrent_api import Client
The PyPI package name is `qbittorrent-api`, but the importable module is `qbittorrentapi`.

This quickstart demonstrates how to connect to a qBittorrent instance using the client library, authenticate, and retrieve basic information like the application version and current transfer speeds. It uses environment variables for sensitive connection details.

import os from qbittorrentapi import Client, APIError # Configure connection details using environment variables for security QBT_HOST = os.environ.get('QBT_HOST', 'localhost') QBT_PORT = int(os.environ.get('QBT_PORT', '8080')) QBT_USERNAME = os.environ.get('QBT_USERNAME', 'admin') QBT_PASSWORD = os.environ.get('QBT_PASSWORD', 'adminadmin') # Change 'adminadmin' if using a custom password try: # Initialize the qBittorrent client qbt_client = Client( host=QBT_HOST, port=QBT_PORT, username=QBT_USERNAME, password=QBT_PASSWORD, verify_data_path=False # Set to True if using HTTPS with a valid certificate ) # Test connection and authentication by getting the application version app_version = qbt_client.app.version() print(f"Successfully connected to qBittorrent Web UI (v{app_version}) at {QBT_HOST}:{QBT_PORT}") # Example: Get the transfer info transfer_info = qbt_client.transfer.info() print(f"Download speed: {transfer_info.dl_info_speed / 1024:.2f} KB/s, Upload speed: {transfer_info.up_info_speed / 1024:.2f} KB/s") except APIError as e: print(f"qBittorrent API Error: {e}") if "failed to login" in str(e).lower(): print("Please check your username and password.") except ConnectionError as e: print(f"Connection Error: {e}. Is qBittorrent running, Web UI enabled, and host/port correct?") except Exception as e: print(f"An unexpected error occurred: {e}")
Debug
Known issues
breakingPython 3.8 support was officially dropped in version `2024.11.69`.
fix
Upgrade your Python environment to 3.9 or newer. Alternatively, pin the `qbittorrent-api` library to a version prior to `2024.11.69` if you must use Python 3.8.
affects: <2024.11.69
gotchaThe library is designed for qBittorrent v4.1+ Web API, but specific features and endpoints may require a newer qBittorrent server version than the minimum supported.
fix
Always check the official qBittorrent Web API documentation and the `qbittorrent-api` changelog for features introduced with specific qBittorrent server versions. Ensure your qBittorrent server is up-to-date for the desired functionality.
affects: all
gotchaIncorrect connection parameters (host, port, username, password) or an inaccessible qBittorrent Web UI will lead to connection or authentication failures.
fix
Verify that qBittorrent is running, its Web UI is enabled, and the host/port are correctly configured and accessible from where the Python script is executed. Double-check your username and password in the qBittorrent Web UI settings.
affects: all
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'qbittorrent_api'
Attempting to import from 'qbittorrent_api' instead of 'qbittorrentapi'. The PyPI package name uses a hyphen, but the Python module name uses an underscore.
fix
Change your import statement to `from qbittorrentapi import Client`.
requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))
The qBittorrent Web UI is not running, is inaccessible from the client's host/port, or the provided host/port in the `Client` constructor are incorrect.
fix
Ensure the qBittorrent application is running, the Web UI is enabled in its settings, and the `host` and `port` parameters passed to `qbittorrentapi.Client` match your qBittorrent configuration and network accessibility.
qbittorrentapi.exceptions.APIError: Failed to login.
The username or password provided to the `Client` constructor are incorrect for the qBittorrent Web UI.
fix
Verify your qBittorrent Web UI username and password in qBittorrent's settings (Tools > Options > Web UI). Update the `username` and `password` parameters in your `qbittorrentapi.Client` constructor accordingly.
Upgrade
Version history
2026.6.0latest on PyPI · released Jun 6, 2026
Audit
Dependencies
requestsrequiredUsed for making HTTP requests to the qBittorrent Web API.
Agent activity
11 hits · last 30 days
node
9
OpenAI (training)
1
Resources
qbittorrent-api — pip install qbittorrent-api · libregistry