{"id":10183,"library":"qbittorrent-api","title":"qbittorrent-api Python Client","description":"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.","status":"active","version":"2025.11.1","language":"en","source_language":"en","source_url":"https://github.com/rmartin16/qbittorrent-api","tags":["bittorrent","qbittorrent","api-client","web-api","torrent-management"],"install":[{"cmd":"pip install qbittorrent-api","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for making HTTP requests to the qBittorrent Web API.","package":"requests","optional":false}],"imports":[{"note":"The PyPI package name is `qbittorrent-api`, but the importable module is `qbittorrentapi`.","wrong":"from qbittorrent_api import Client","symbol":"Client","correct":"from qbittorrentapi import Client"}],"quickstart":{"code":"import os\nfrom qbittorrentapi import Client, APIError\n\n# Configure connection details using environment variables for security\nQBT_HOST = os.environ.get('QBT_HOST', 'localhost')\nQBT_PORT = int(os.environ.get('QBT_PORT', '8080'))\nQBT_USERNAME = os.environ.get('QBT_USERNAME', 'admin')\nQBT_PASSWORD = os.environ.get('QBT_PASSWORD', 'adminadmin') # Change 'adminadmin' if using a custom password\n\ntry:\n    # Initialize the qBittorrent client\n    qbt_client = Client(\n        host=QBT_HOST,\n        port=QBT_PORT,\n        username=QBT_USERNAME,\n        password=QBT_PASSWORD,\n        verify_data_path=False # Set to True if using HTTPS with a valid certificate\n    )\n\n    # Test connection and authentication by getting the application version\n    app_version = qbt_client.app.version()\n    print(f\"Successfully connected to qBittorrent Web UI (v{app_version}) at {QBT_HOST}:{QBT_PORT}\")\n\n    # Example: Get the transfer info\n    transfer_info = qbt_client.transfer.info()\n    print(f\"Download speed: {transfer_info.dl_info_speed / 1024:.2f} KB/s, Upload speed: {transfer_info.up_info_speed / 1024:.2f} KB/s\")\n\nexcept APIError as e:\n    print(f\"qBittorrent API Error: {e}\")\n    if \"failed to login\" in str(e).lower():\n        print(\"Please check your username and password.\")\nexcept ConnectionError as e:\n    print(f\"Connection Error: {e}. Is qBittorrent running, Web UI enabled, and host/port correct?\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Python 3.8 support was officially dropped in version `2024.11.69`.","severity":"breaking","affected_versions":"<2024.11.69"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"Incorrect connection parameters (host, port, username, password) or an inaccessible qBittorrent Web UI will lead to connection or authentication failures.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Change your import statement to `from qbittorrentapi import Client`.","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.","error":"ModuleNotFoundError: No module named 'qbittorrent_api'"},{"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.","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.","error":"requests.exceptions.ConnectionError: ('Connection aborted.', ConnectionRefusedError(111, 'Connection refused'))"},{"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.","cause":"The username or password provided to the `Client` constructor are incorrect for the qBittorrent Web UI.","error":"qbittorrentapi.exceptions.APIError: Failed to login."}]}