qbittorrent-api 2025.11.1
Python client for qBittorrent v4.1+ Web API.
Requires Python: >=3.9
Keywords: python, qbittorrent, api, client, torrent, torrents, webui, web

<div align="center">

qBittorrent Web API Client
==========================

Python client implementation for qBittorrent Web API

[![GitHub Workflow Status (branch)](https://img.shields.io/github/checks-status/rmartin16/qbittorrent-api/main?style=flat-square)](https://github.com/rmartin16/qbittorrent-api/actions?query=branch%3Amain) [![Codecov branch](https://img.shields.io/codecov/c/gh/rmartin16/qbittorrent-api/main?style=flat-square)](https://app.codecov.io/gh/rmartin16/qbittorrent-api) [![PyPI](https://img.shields.io/pypi/v/qbittorrent-api?style=flat-square)](https://pypi.org/project/qbittorrent-api/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/qbittorrent-api?style=flat-square)](https://pypi.org/project/qbittorrent-api/)

</div>

Currently supports qBittorrent [v5.1.4](https://github.com/qbittorrent/qBittorrent/releases/tag/release-5.1.4) (Web API v2.11.4) released on Nov 19, 2025.

User Guide and API Reference available on [Read the Docs](https://qbittorrent-api.readthedocs.io/).

Features
--------
* The entire qBittorrent [Web API](https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)) 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](https://pypi.org/project/qbittorrent-api/)
```bash
python -m pip install qbittorrent-api
```

Getting Started
---------------
```python
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()
```

Change Log
==========
### v2025.11.1 (20 nov 2025)
- Advertise support for qBittorrent v5.1.4

### v2025.11.0 (10 nov 2025)
- Advertise support for qBittorrent v5.1.3

### v2025.7.0 (12 jul 2025)
- Advertise support for qBittorrent v5.1.1
- Advertise support for qBittorrent v5.1.2

### v2025.5.0 (02 may 2025)
- Advertise support for qBittorrent v5.1.0
- Existing changes that are now supported in qBittorrent:
  - Add support for managing cookies (#492)
    - ``app/cookies``
    - ``app/setCookies``
  - Add support for WebSeed modification endpoints (#481)
    - ``torrents/addWebSeeds``
    - ``torrents/editWebSeed``
    - ``torrents/removeWebSeeds``
  - Add support for ``torrents/setTags`` (#512)

### v2025.4.1 (24 apr 2025)
- Add SPDX license to package (#529)

### v2025.4.0 (19 apr 2025)
- Advertise support for qBittorrent v5.0.5

### v2025.2.0 (17 feb 2025)
- Advertise support for qBittorrent v5.0.4

### v2024.12.71 (21 dec 2024)
- Advertise support for qBittorrent v5.0.3
- Advertise support for qBittorrent v5.1.0beta1
- Add support to add torrent as forced (#507)

### v2024.11.70 (20 nov 2024)
- Advertise support for qBittorrent v5.0.2

### v2024.11.69 (16 nov 2024)
- Dropped support for Python 3.8 (#494)
- Fixed typing for ``content_layout`` for ``torrents.add()`` (#499)
- ``RecursionError`` is no longer raised when client is banned (#501)

### v2024.10.68 (28 oct 2024)
- Advertise support for qBittorrent v5.0.1
- Add support for managing cookies (#492)
  - ``app/cookies``
  - ``app/setCookies``
  - Note: these endpoints are scheduled for release in qBittorrent v5.1.0

### v2024.9.67 (30 sept 2024)
- Advertise support for qBittorrent v5.0.0
- Features previously added for v5.0.0 release:
  - Rename resume/pause actions for torrents to start/stop (#434)
    - For instance, ``client.torrents_pause()`` is now ``client.torrents_stop()``
    - All existing method and argument names are still supported and are aliased to the new names
  - Add support for ``app/getDirectoryContent`` (#449)
  - Add support for ``search/downloadTorrent`` (#451)
  - Added support for ``private`` argument for ``torrents/info`` (#464)
  - Add support for WebSeed modification endpoints (#481)

### v2024.9.66 (16 sept 2024)
- Advertise support for qBittorrent v4.6.7

### v2024.8.65 (19 aug 2024)
- Advertise support for qBittorrent v4.6.6 and 5.0.0rc1 (#482)
- Add support for WebSeed modification endpoints (#481)
  - ``torrents/addWebSeeds``
  - ``torrents/editWebSeed``
  - ``torrents/removeWebSeeds``

### v2024.7.64 (18 jul 2024)
- Resolve errors from type checkers for ``functools.wraps`` usage (#472)
- Included changes for upcoming qBittorrent v5.0.0 release:
  - Added support for ``private`` argument for ``torrents/info`` (#464)

### v2024.5.63 (31 may 2024)
- Added support to configure ``HTTPAdapter`` (#459)

### v2024.5.62 (29 may 2024)
- Minor typing fixes (#456, #457)

### v2024.5.61 (26 may 2024)
- Advertise support for qBittorrent v4.6.5
- Packages published to PyPI are now attested by GitHub (#453)
- Included changes for upcoming qBittorrent v5.0.0 release:
  - Rename resume/pause actions for torrents to start/stop (#434)
    - For instance, ``client.torrents_pause()`` is now ``client.torrents_stop()``
    - All existing method and argument names are still supported and are aliased to the new names
  - Add support for ``app/getDirectoryContent`` (#449)
  - Add support for ``search/downloadTorrent`` (#451)

### v2024.3.60 (25 mar 2024)
- Advertise support for qBittorrent v4.6.4

### v2024.2.59 (25 feb 2024)
- Allow added RSS feeds without a name/path to default to the name in the feed (#423)
- Advertise support for Python 3.13 (#349)

### v2024.1.58 (16 jan 2024)
- Advertise support for qBittorrent v4.6.3

### v2023.11.57 (27 nov 2023)
- Advertise support for qBittorrent v4.6.2

### v2023.11.56 (20 nov 2023)
- Advertise support for qBittorrent v4.6.1
- Add support for ``torrents/count`` (#366)

### v2023.11.55 (6 nov 2023)
- Remove Python 2 platform tag from published wheel (#369)

### v2023.10.54 (22 oct 2023)
- Advertise support for qBittorrent v4.6.0
- Dropped support for legacy Python versions; Python 3.8+ is supported (#333)
- Refactored typing from stub files in to source (#345)
- Dropped support for API method arguments ``hash`` and ``hashes``; use ``torrent_hash`` and ``torrent_hashes``, respectively (#345)
  - For example, replace ``client.torrents_info(hashes="...")`` with ``client.torrents_info(torrent_hashes="...")``

### v2023.9.53 (7 sept 2023)
- Advertise support for Python 3.12
- Advertise support for qBittorrent v4.5.5
- Add ``inactive_seeding_time_limit`` for ``torrents/setShareLimits`` (#271)
- Implement ``app/networkInterfaceList`` and ``app/networkInterfaceAddressList`` (#272)

### v2023.7.52 (13 jul 2023)
- Ensure the wheel is uploaded with the release to PyPI

### v2023.7.51 (13 jul 2023)
- Convert ``APINames`` and ``TorrentStatus`` to ``StrEnum`` and ``TrackerStatus`` to ``IntEnum`` (#267)

### v2023.6.50 (19 jun 2023)
- Advertise support for qBittorrent v4.5.4

### v2023.6.49 (9 jun 2023)
- The ``Client`` is no longer binded to ``List``s (#230)
- This does not affect normal operation but allows for slicing, adding, and copying ``List``s

### v2023.5.48 (29 may 2023)
- Advertise support for qBittorrent v4.5.3

### v2023.4.47 (19 apr 2023)
- ``Client`` can now be used as a context manager

### v2023.4.46 (14 apr 2023)
- Fix building docs after implementing ``src-layout``

### v2023.4.45 (11 apr 2023)
- Add the ``TrackerStatus`` Enum to identify tracker statuses from ``torrents/trackers``

### v2023.3.44 (09 mar 2023)
- Add support for torrent status filters ``seeding``, ``moving``, ``errored``, and ``checking``

### v2023.2.43 (27 feb 2023)
- Advertise support for qBittorrent v4.5.2

### v2023.2.42 (13 feb 2023)
- Advertise support for qBittorrent v4.5.1

### v2023.2.41 (8 feb 2023)
- Remove dependence on qBittorrent authentication cookie being named ``SID``
- Minor typing fixes

### v2022.11.40 (27 nov 2022)
- Support qBittorrent v4.5.0 release
- Add support for ``torrents/export``
- Implement new ``transfer/setSpeedLimitsMode`` in place of existing ``transfer/toggleSpeedLimitsMode``
- Add support for ``stopCondition`` in ``torrents/add``
- Update typing to be complete, accurate, and shipped with the package

### v2022.10.39 (26 oct 2022)
- Advertise support for Python 3.11

### v2022.8.38 (31 aug 2022)
- Advertise support for qBittorrent v4.4.5

### v2022.8.37 (24 aug 2022)
- Advertise support for qBittorrent v4.4.4

### v2022.8.36 (15 aug 2022)
- Comply with enforced HTTP method requirements from qBittorrent

### v2022.8.35 (13 aug 2022)
- Remove ``PYTHON_`` prefix for configuration environment variables

### v2022.8.34 (11 aug 2022)
- Add ``setuptools`` as an explicit dependency for ``pkg_resources.parse_version()``

### v2022.7.33 (27 jul 2022)
- Reorder class hierarchy to allow independent MixIn use
- Clean up typing annotations
- Optimize Dictionary and List initializations
- Rename Alias decorator to alias for better conformity

### v2022.5.32 (30 may 2022)
- Implement pre-commit checks
- Advertise support for qBittorrent v4.4.3.1

### v2022.5.31 (24 may 2022)
- Advertise support for qBittorrent v4.4.3
- Revamp GitHub CI
- Reorg ``Request`` for some more clarity (hopefully)

### v2022.4.30 (3 apr 2022)
- Stop advertising support for Python 3.6 (EOL 12/2021)
- Publish to PyPI using API token and cleanup GitHub Action scripts

### v2022.3.29 (25 mar 2022)
- Advertise support for qBittorrent v4.4.2

### v2022.2.28 (17 feb 2022)
- Advertise support for qBittorrent v4.4.1
- qBittorrent reverted the category dictionary key ``savePath`` back to ``save_path``

### v2022.1.27 (9 jan 2022)
- Support for qBittorrent v4.4.0
- ``torrents/info`` results can now be filtered by a torrent tag
- Added new torrent state "Forced Metadata Downloading"
- Support per-torrent/per-category "download folder"

### v2021.12.26 (11 dec 2021)
- Stop sending ``Origin`` and ``Referer`` headers (Fixes #63)

### v2021.12.25 (10 dec 2021)
- Close files that are opened and sent to Requests when adding torrents from files
- Enable warnings for tests and explicitly close Requests Sessions to prevent (mostly spurious) ResourceWarnings

### v2021.12.24 (3 dec 2021)
- Add Type Hints for all public and private functions, methods, and variables
- Support HTTP timeouts as well as arbitrary Requests configurations

### v2021.8.23 (28 aug 2021)
- Advertise support for qBittorrent v4.3.8
- Drop support for Python 3.5

### v2021.5.22 (12 may 2021)
- Support for qBittorrent v4.3.5
- ``torrents/files`` includes ``index`` for each file; ``index`` officially replaces ``id`` but ``id`` will still be populated

### v2021.5.21 (1 may 2021)
- Allow users to force a specific communications scheme with ``FORCE_SCHEME_FROM_HOST`` (fixes #54)

### v2021.4.20 (11 apr 2021)
- Add support for ratio limit and seeding time limit when adding torrents

### v2021.4.19 (8 apr 2021)
- Update license in setup to match gpl->mit license change on GitHub

### v2021.3.18 (13 mar 2021)
- Replace ``TorrentStates.FORCE_DOWNLOAD='forceDL'`` with ``TorrentStates.FORCED_DOWNLOAD='forcedDL'``

### v2021.2.17 (7 feb 2021)
- Generally refactor ``requests.py`` so it's better and easier to read
- Persist a Requests Session between API calls instead of always creating a new one...small perf benefit
- Move auth endpoints back to a dedicated module
- Since ``attrdict`` is apparently going to break in Python 3.10 and it is no longer maintained, I've vendored a modified version (fixes #45)
- Created ``handle_hashes`` decorator to hide the cruft of continuing to support hash and hashes arguments

### v2021.1.16 (26 jan 2021)
- Support qBittorrent v4.3.3 and Web API v2.7 (...again)
- New ``torrents/renameFile`` and ``torrents/renameFolder`` endpoints
- Retrieve app api version when needed instead of caching
- Stop verifying and removing individual parameters when they aren't supported

### v2020.12.15 (27 dec 2020)
- Support qBittorrent v4.3.2 and Web API v2.7
- ``torrents/add`` supports adding torrents with tags via ``tags`` parameter
- ``app/preferences`` supports toggling internationalized domain name (IDN) support via ``idn_support_enabled``
- BREAKING CHANGE: for ``torrents/add``, ``is_root_folder`` (or ``root_folder``) is superseded by ``content_layout``
- For ``torrents/delete``, ``delete_files`` now defaults to ``False`` instead of required being explicitly passed

### v2020.12.14 (6 dec 2020)
- Add support for non-standard API endpoint paths (Fixes #37)
- Allows users to leverage this client when qBittorrent is configured behind a reverse proxy
  - For instance, if the Web API is being exposed at "http://localhost/qbt/", then users can instantiate via ``Client(host='localhost/qbt')`` and all API endpoint paths will be prefixed with "/qbt"
- Additionally, the scheme (i.e. http or https) from the user will now be respected as the first choice for which scheme is used to communicate with qBittorrent
  - However, users still don't need to even specify a scheme; it'll be automatically determined on the first connection to qBittorrent
- Neither of these should be breaking changes, but if you're instantiating with an incorrect scheme or an irrelevant path, you may need to prevent doing that now

### v2020.11.13 (29 nov 2020)
- Support qBittorrent v4.3.1 and Web API v2.6.1
- Path of torrent content now available via ``content_path`` from ``torrents/info``

### v2020.11.12 (16 nov 2020)
- Fix support for raw bytes for ``torrent_files`` in ``torrents_add()`` for Python 3 (Fixes #34)

### v2020.10.11 (29 oct 2020)
- Support qBittorrent v4.3.0.1 and Web API v2.6
- Due to qBittorrent changes, ``search/categories`` no longer returns anything and ``rss/renameRule`` works again

### v2020.10.10 (7 oct 2020)
- Advertise support for Python 3.9

### v2020.9.9 (12 sept 2020)
- Only request ``enum34`` for Python 2

### v2020.8.8 (14 aug 2020)
- Support adding torrents from raw torrent files as bytes or file handles (Fixes #23)
- Introduce ``TorrentStates`` enum for qBittorrent list of torrent states

### v2020.7.7 (26 jul 2020)
- Update tests and misc small fixes

### v2020.7.6 (25 jul 2020)
- Re-release of v2020.7.5

### v2020.7.5 (25 jul 2020)
- Add RTD documentation

### v2020.6.4 (9 jun 2020)
- Bug fix release. Reorganized code and classes to be more logical
- Started returning None from many methods that were returning Requests Responses
- Content-Length header is now explicitly sent as "0" for any POSTs without a body
- Endpoint input parameters ``hash`` and ``hashes`` are renamed to ``torrent_hash`` and ``torrent_hashes``. ``hash`` and ``hashes`` remain supported
- ``search_uninstall_plugin`` now works. search_enable_plugin now supports multiple plugins
- ``Torrent.download_limit`` now only return the value instead of a dictionary. ``Torrent.upload_limit`` now works
- Drop advertising Python 2.6 and 3.4 support; add PyPy3 support
- Implement test suite and CI that can test all supported qBittorrent versions on all pythons

### v2020.5.3 (11 may 2020)
- Include currently supported qBittorrent version in README (Fixes #11)

### v2020.4.2 (25 apr 2020)
- Add support for ``rss/markAsRead`` and ``rss/matchingArticles``. Added in v2.5.1 (Fixes #10)

### v2020.4.1 (25 apr 2020)
- Add ``stalled()``, ``stalled_uploading()``, and ``stalled_downloading()`` to ``torrents.info`` interaction; added in Web API v2.4.1
- Implement torrent file renaming. Added in Web API v2.4.0 (Fixes #3)
- Since versioning was botched last release, implement calendar versioning
- List of files returned from ``torrents_files()`` now contains file ID in ``id``

### v6.0.0 (22 apr 2020)
- Performance gains for responses with payloads...especially for large payloads
- Fixes #6. Adds support for ``SIMPLE_RESPONSES`` for the entire client and individual methods

### v0.5.2 (19 apr 2020)
- Fixes #8. Remove whitespace from in setPreferences requests for older qBittorrent versions

### v0.5.1 (2 jan 2020)
- Add Python3.8 version for PyPI
- Move project from beta to stable for PyPI

### v0.5.0 (2 jan 2020)
- Make Web API URL derivation more robust...thereby allowing the client to actually work on Python3.8 (#5)
- Allow port to be discretely specified during Client instantiation (#4)
- Enhance request retry logic and expose retry configuration

### v0.4.2 (5 dec 2019)
- Improve organization and clarity of README
- Better document exceptions
- Clarify torrent file handling exceptions better with proper exceptions
- Clean up the request wrapper exception handling
- Fix HTTP 404 handling to find and return problematic torrent hashes

### v0.4.1 (4 dec 2019)
- Round out support for tags with qBittorrent v4.2.0 release
- Remove upper-bound version requirements for ``requests`` and ``urllib3``

### v0.4 (4 dec 2019)
- Support for qBittorrent v4.2.0 release
- Add support for ``app/buildInfo``
- Add support for ``transfer/banPeers`` and ``torrents/addPeers``
- Add support for ``torrents/addTags``, ``torrents/removeTags``, ``torrents/tags``, ``torrents/createTags``, and ``torrents/deleteTags``

### v0.3.3 (29 sept 2019)
- Fix useAutoTMM to autoTMM for ``client.torrents_add()`` so auto torrent management works
- Add support to refresh RSS items introduced in qBittorrent v4.1.8

### v0.3.2 (28 jun 2019)
- Restore python 2 compatibility
- Allow exceptions to be imported directly from package instead of only exceptions module

### v0.3 (1 jun 2019)
- Finalized interaction layer interfaces

### v0.2 (13 may 2019)
- Introduced the "interaction layer" for transparent interaction with the qBittorrent API

### v0.1 (7 may 2019)
- Complete implementation of qBittorrent WebUI API 2.2
- Each API endpoint is available via the ``Client`` class
- Automatic re-login is supported in the event of login expiration

MIT License

Copyright (c) Russell Martin

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.