qbittorrent-api Python Client

2025.11.1 · active · verified Fri Apr 17

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.

Common errors

```
ModuleNotFoundError: No module named 'qbittorrent_api'
```
cause 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'))
```
cause 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.
```
cause 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.

Warnings

breaking Python 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.
gotcha The 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.
gotcha Incorrect 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.

Install

pip install qbittorrent-api Install latest version

Imports

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

Quickstart

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

view raw JSON →