qBittorrent Web API Client¶

Introduction¶

pypi versions pypi implementations

Python client implementation for qBittorrent Web API.

Currently supports up to qBittorrent v4.3.0.1 (Web API v2.6.0) released on October 22, 2020.

The full qBittorrent Web API documentation is available on their wiki.

Features¶

The entire qBittorent Web API is implemented.
qBittorrent version checking for an endpoint’s existence/features is automatically handled.
All Python versions are supported.
If the authentication cookie expires, a new one is automatically requested in line with any API call.

Installation¶

Install via pip from PyPI:
- pip install qbittorrent-api
Install specific release:
- pip install git+https://github.com/rmartin16/qbittorrent-api.git@v2020.6.4#egg=qbittorrent-api
Install direct from master:
- pip install git+https://github.com/rmartin16/qbittorrent-api.git#egg=qbittorrent-api
Ensure urllib3, requests, and attrdict are installed. (These are installed automatically using the methods above.)
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
qbt_client = qbittorrentapi.Client(host='localhost:8080', username='admin', password='adminadmin')

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

# 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})')

# pause all torrents
qbt_client.torrents.pause.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.pause.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

Introduction¶

pypi versions pypi implementations

Python client implementation for qBittorrent Web API.

Currently supports up to qBittorrent v4.3.0.1 (Web API v2.6.0) released on October 22, 2020.

The full qBittorrent Web API documentation is available on their wiki.

Features¶

The entire qBittorent Web API is implemented.
qBittorrent version checking for an endpoint’s existence/features is automatically handled.
All Python versions are supported.
If the authentication cookie expires, a new one is automatically requested in line with any API call.

Installation¶

Install via pip from PyPI:
- pip install qbittorrent-api
Install specific release:
- pip install git+https://github.com/rmartin16/qbittorrent-api.git@v2020.6.4#egg=qbittorrent-api
Install direct from master:
- pip install git+https://github.com/rmartin16/qbittorrent-api.git#egg=qbittorrent-api
Ensure urllib3, requests, and attrdict are installed. (These are installed automatically using the methods above.)
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
qbt_client = qbittorrentapi.Client(host='localhost:8080', username='admin', password='adminadmin')

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

# 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})')

# pause all torrents
qbt_client.torrents.pause.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.pause.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

Behavior & Configuration¶

Untrusted WebUI Certificate¶

qBittorrent allows you to configure HTTPS with an untrusted certificate; this commonly includes self-signed certificates.
When using such a certificate, instantiate Client with VERIFY_WEBUI_CERTIFICATE=False or set environment variable PYTHON_QBITTORRENTAPI_DO_NOT_VERIFY_WEBUI_CERTIFICATE to a non-null value.
Failure to do this for will cause connections to qBittorrent to fail.
As a word of caution, doing this actually does turn off certificate verification. Therefore, for instance, potential man-in-the-middle attacks will not be detected and reported (since the error is suppressed). However, the connection will remain encrypted.

Host, Username and Password¶

These can be provided when instantiating Client or calling qbt_client.auth_log_in(username='...', password='...').
Alternatively, set environment variables PYTHON_QBITTORRENTAPI_HOST, PYTHON_QBITTORRENTAPI_USERNAME and PYTHON_QBITTORRENTAPI_PASSWORD.

Unimplemented API Endpoints¶

Since the qBittorrent Web API has evolved over time, some endpoints may not be available from the qBittorrent host.
By default, if a call is made to endpoint that doesn’t exist for the version of the qBittorrent host (e.g., the Search endpoints were introduced in Web API v2.1.1), there’s a debug logger output and None is returned.
To raise NotImplementedError instead, instantiate Client with RAISE_NOTIMPLEMENTEDERROR_FOR_UNIMPLEMENTED_API_ENDPOINTS=True.

Disable Logging Debug Output¶

Instantiate Client with DISABLE_LOGGING_DEBUG_OUTPUT=True or manually disable logging for the relevant packages:
- logging.getLogger('qbittorrentapi').setLevel(logging.INFO)
- logging.getLogger('requests').setLevel(logging.INFO)
- logging.getLogger('urllib3').setLevel(logging.INFO)

Performance¶

By default, complex objects are returned from some endpoints. These objects allow for accessing the response’s items as attributes and include methods for contextually relevant actions (such as start() and stop() for a torrent, for example).

This comes at the cost of performance, though. Generally, this cost isn’t large; however, some endpoints, such as torrents_files(), may need to convert a large payload and the cost can be significant.

This client can be configured to always return only the simple JSON if desired. Simply set SIMPLE_RESPONSES=True when instantiating the client.

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

Alternatively, SIMPLE_RESPONSES can be set to True to return the simple JSON only for an individual method call.

qbt_client.torrents.files(torrent_hash='...', SIMPLE_RESPONSES=True)

Exceptions¶

exception qbittorrentapi.exceptions.APIError¶

Bases: Exception

Base error for all exceptions from this Client.

exception qbittorrentapi.exceptions.FileError¶

Bases: OSError, qbittorrentapi.exceptions.APIError

Base class for all exceptions for file handling.

exception qbittorrentapi.exceptions.TorrentFileError¶

Bases: qbittorrentapi.exceptions.FileError

Base class for all exceptions for torrent files.

exception qbittorrentapi.exceptions.TorrentFileNotFoundError¶

Bases: qbittorrentapi.exceptions.TorrentFileError

Specified torrent file does not appear to exist.

exception qbittorrentapi.exceptions.TorrentFilePermissionError¶

Bases: qbittorrentapi.exceptions.TorrentFileError

Permission was denied to read the specified torrent file.

exception qbittorrentapi.exceptions.APIConnectionError(*args, **kwargs)¶

Bases: requests.exceptions.RequestException, qbittorrentapi.exceptions.APIError

Base class for all communications errors including HTTP errors.

exception qbittorrentapi.exceptions.LoginFailed(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.APIConnectionError

This can technically be raised with any request since log in may be attempted for any request and could fail.

exception qbittorrentapi.exceptions.HTTPError(*args, **kwargs)¶

Bases: requests.exceptions.HTTPError, qbittorrentapi.exceptions.APIConnectionError

Base error for all HTTP errors. All errors following a successful connection to qBittorrent are returned as HTTP statuses.

exception qbittorrentapi.exceptions.HTTP4XXError(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTPError

Base error for all HTTP 4XX statuses.

exception qbittorrentapi.exceptions.HTTP5XXError(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTPError

Base error for all HTTP 5XX statuses.

exception qbittorrentapi.exceptions.HTTP400Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP4XXError

HTTP 400 Status

exception qbittorrentapi.exceptions.HTTP401Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP4XXError

HTTP 401 Status

exception qbittorrentapi.exceptions.HTTP403Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP4XXError

HTTP 403 Status

exception qbittorrentapi.exceptions.HTTP404Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP4XXError

HTTP 404 Status

exception qbittorrentapi.exceptions.HTTP409Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP4XXError

HTTP 409 Status

exception qbittorrentapi.exceptions.HTTP415Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP4XXError

HTTP 415 Status

exception qbittorrentapi.exceptions.HTTP500Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP5XXError

HTTP 500 Status

exception qbittorrentapi.exceptions.MissingRequiredParameters400Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP400Error

Endpoint call is missing one or more required parameters.

exception qbittorrentapi.exceptions.InvalidRequest400Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP400Error

One or more endpoint arguments are malformed.

exception qbittorrentapi.exceptions.Unauthorized401Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP401Error

Primarily reserved for XSS and host header issues.

exception qbittorrentapi.exceptions.Forbidden403Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP403Error

Not logged in, IP has been banned, or calling an API method that isn’t public.

exception qbittorrentapi.exceptions.NotFound404Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP404Error

This should mean qBittorrent couldn’t find a torrent for the torrent hash.

exception qbittorrentapi.exceptions.Conflict409Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP409Error

Returned if arguments don’t make sense specific to the endpoint.

exception qbittorrentapi.exceptions.UnsupportedMediaType415Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP415Error

torrents/add endpoint will return this for invalid URL(s) or files.

exception qbittorrentapi.exceptions.InternalServerError500Error(*args, **kwargs)¶

Bases: qbittorrentapi.exceptions.HTTP500Error

Returned if qBittorent craps on itself while processing the request…

API Reference¶

Application¶

class qbittorrentapi.AppAPIMixIn(host='', port=None, username=None, password=None, **kwargs)¶

Implementation of all Application API methods

app_buildInfo(**kwargs)¶

Retrieve build info. (alias: app_buildInfo)

Returns:	Dictionary of build info. Each piece of info is an attribute. Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-build-info

app_build_info(**kwargs)¶

Retrieve build info. (alias: app_buildInfo)

Returns:	Dictionary of build info. Each piece of info is an attribute. Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-build-info

app_defaultSavePath(**kwargs)¶

Retrieves the default path for where torrents are saved. (alias: app_defaultSavePath)

Returns:	string

app_default_save_path(**kwargs)¶

Retrieves the default path for where torrents are saved. (alias: app_defaultSavePath)

Returns:	string

app_preferences(**kwargs)¶

Retrieve qBittorrent application preferences.

Returns:	Dictionary of preferences. Each preference is an attribute. Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-application-preferences

app_setPreferences(prefs=None, **kwargs)¶

Set one or more preferences in qBittorrent application. (alias: app_setPreferences)

Parameters:	prefs – dictionary of preferences to set
Returns:	None

app_set_preferences(prefs=None, **kwargs)¶

Set one or more preferences in qBittorrent application. (alias: app_setPreferences)

Parameters:	prefs – dictionary of preferences to set
Returns:	None

app_shutdown(**kwargs)¶: Shutdown qBittorrent.

app_version(**kwargs)¶

Retrieve application version

Returns:	string

app_web_api_version(**kwargs)¶

Retrieve web API version. (alias: app_webapiVersion)

Returns:	string

app_webapiVersion(**kwargs)¶

Retrieve web API version. (alias: app_webapiVersion)

Returns:	string

application¶

Allows for transparent interaction with Application endpoints. (alias: app)

See Application class for usage. :return: Application object

class qbittorrentapi.Application(*args, **kwargs)¶

Allows interaction with “Application” API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host='localhost:8080', username='admin', password='adminadmin')
>>> # this are all the same attributes that are available as named in the
>>> #  endpoints or the more pythonic names in Client (with or without 'app_' prepended)
>>> webapiVersion = client.application.webapiVersion
>>> web_api_version = client.application.web_api_version
>>> app_web_api_version = client.application.app_web_api_version
>>> # access and set preferences as attributes
>>> is_dht_enabled = client.application.preferences.dht
>>> # supports sending a just subset of preferences to update
>>> client.application.preferences = dict(dht=(not is_dht_enabled))
>>> prefs = client.application.preferences
>>> prefs['web_ui_clickjacking_protection_enabled'] = True
>>> client.app.preferences = prefs
>>>
>>> client.application.shutdown()

buildInfo¶

build_info¶

defaultSavePath¶

default_save_path¶

preferences¶

setPreferences(prefs=None, **kwargs)¶

set_preferences(prefs=None, **kwargs)¶

shutdown()¶

version¶

web_api_version¶

webapiVersion¶

Authentication¶

class qbittorrentapi.Request(host='', port=None, username=None, password=None, **kwargs)¶

Facilitates HTTP requests to qBittorrent.

auth_log_in(username=None, password=None)¶

Log in to qBittorrent host.

Raises:	LoginFailed – if credentials failed to log in Forbidden403Error – if user user is banned…or not logged in
Parameters:	username – user name for qBittorrent client password – password for qBittorrent client
Returns:	None

auth_log_out(**kwargs)¶: End session with qBittorrent.

Client¶

class qbittorrentapi.Client(host='', port=None, username=None, password=None, **kwargs)¶

Initialize API for qBittorrent client.

Host must be specified. Username and password can be specified at login. A call to auth_log_in is not explicitly required if username and password are provided during Client construction.

Parameters:

host – hostname for qBittorrent Web API (e.g. [http[s]://]localhost[:8080])
port – port number for qBittorrent Web API (note: only used if host does not contain a port)
username – user name for qBittorrent client
password – password for qBittorrent client
SIMPLE_RESPONSES – By default, complex objects are returned from some endpoints. These objects will allow for accessing responses’ items as attributes and include methods for contextually relevant actions. This comes at the cost of performance. Generally, this cost isn’t large; however, some endpoints, such as torrents_files() method, may need to convert a large payload. Set this to True to return the simple JSON back. Alternatively, set this to True only for an individual method call. For instance, when requesting the files for a torrent: client.torrents_files(hash=’…’, SIMPLE_RESPONSES=True).
VERIFY_WEBUI_CERTIFICATE – Set to False to skip verify certificate for HTTPS connections; for instance, if the connection is using a self-signed certificate. Not setting this to False for self-signed certs will cause a APIConnectionError exception to be raised.
RAISE_UNIMPLEMENTEDERROR_FOR_UNIMPLEMENTED_API_ENDPOINTS – Some Endpoints may not be implemented in older versions of qBittorrent. Setting this to True will raise a UnimplementedError instead of just returning None.
DISABLE_LOGGING_DEBUG_OUTPUT – Turn off debug output from logging for this package as well as Requests & urllib3.

Log¶

class qbittorrentapi.LogAPIMixIn(host='', port=None, username=None, password=None, **kwargs)¶

Implementation of all Log API methods.

log_main(normal=None, info=None, warning=None, critical=None, last_known_id=None, **kwargs)¶

Retrieve the qBittorrent log entries. Iterate over returned object.

Parameters:	normal – False to exclude ‘normal’ entries info – False to exclude ‘info’ entries warning – False to exclude ‘warning’ entries critical – False to exclude ‘critical’ entries last_known_id – only entries with an ID greater than this value will be returned
Returns:	List of log entries.

log_peers(last_known_id=None, **kwargs)¶

Retrieve qBittorrent peer log.

Parameters:	last_known_id – only entries with an ID greater than this value will be returned
Returns:	list of log entries in a List

class qbittorrentapi.Log(client)¶

Allows interaction with “Log” API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host='localhost:8080', username='admin', password='adminadmin')
>>> # this is all the same attributes that are available as named in the
>>> #  endpoints or the more pythonic names in Client (with or without 'log_' prepended)
>>> log_list = client.log.main()
>>> peers_list = client.log.peers(hash='...')
>>> # can also filter log down with additional attributes
>>> log_info = client.log.main.info(last_known_id='...')
>>> log_warning = client.log.main.warning(last_known_id='...')

peers(last_known_id=None, **kwargs)¶

RSS¶

class qbittorrentapi.RSSAPIMixIn(host='', port=None, username=None, password=None, **kwargs)¶

Implementation of all RSS API methods.

rss_addFeed(url=None, item_path=None, **kwargs)¶

Add new RSS feed. Folders in path must already exist. (alias: rss_addFeed)

Raises:	Conflict409Error –
Parameters:	url – URL of RSS feed (e.g http://thepiratebay.org/rss/top100/200) item_path – Name and/or path for new feed (e.g. FolderSubfolderFeedName)
Returns:	None

rss_addFolder(folder_path=None, **kwargs)¶

Add a RSS folder. Any intermediate folders in path must already exist. (alias: rss_addFolder)

Raises:	Conflict409Error –
Parameters:	folder_path – path to new folder (e.g. LinuxISOs)
Returns:	None

rss_add_feed(url=None, item_path=None, **kwargs)¶

Add new RSS feed. Folders in path must already exist. (alias: rss_addFeed)

Raises:	Conflict409Error –
Parameters:	url – URL of RSS feed (e.g http://thepiratebay.org/rss/top100/200) item_path – Name and/or path for new feed (e.g. FolderSubfolderFeedName)
Returns:	None

rss_add_folder(folder_path=None, **kwargs)¶

Add a RSS folder. Any intermediate folders in path must already exist. (alias: rss_addFolder)

Raises:	Conflict409Error –
Parameters:	folder_path – path to new folder (e.g. LinuxISOs)
Returns:	None

rss_items(include_feed_data=None, **kwargs)¶

Retrieve RSS items and optionally feed data.

Parameters:	include_feed_data – True or false to include feed data
Returns:	dictionary of RSS items

rss_markAsRead(item_path=None, article_id=None, **kwargs)¶

Mark RSS article as read. If article ID is not provider, the entire feed is marked as read. (alias: rss_markAsRead)

Raises:	NotFound404Error –
Parameters:	item_path – path to item to be refreshed (e.g. FolderSubfolderItemName) article_id – article ID from rss_items()
Returns:	None

rss_mark_as_read(item_path=None, article_id=None, **kwargs)¶

Mark RSS article as read. If article ID is not provider, the entire feed is marked as read. (alias: rss_markAsRead)

Raises:	NotFound404Error –
Parameters:	item_path – path to item to be refreshed (e.g. FolderSubfolderItemName) article_id – article ID from rss_items()
Returns:	None

rss_matchingArticles(rule_name=None, **kwargs)¶

Fetch all articles matching a rule. (alias: rss_matchingArticles)

Parameters:	rule_name – Name of rule to return matching articles
Returns:	RSSitemsDictionary of articles

rss_matching_articles(rule_name=None, **kwargs)¶

Fetch all articles matching a rule. (alias: rss_matchingArticles)

Parameters:	rule_name – Name of rule to return matching articles
Returns:	RSSitemsDictionary of articles

rss_moveItem(orig_item_path=None, new_item_path=None, **kwargs)¶

Move/rename a RSS item (folder, feed, etc). (alias: rss_moveItem)

Raises:	Conflict409Error –
Parameters:	orig_item_path – path to item to be removed (e.g. FolderSubfolderItemName) new_item_path – path to item to be removed (e.g. FolderSubfolderItemName)
Returns:	None

rss_move_item(orig_item_path=None, new_item_path=None, **kwargs)¶

Move/rename a RSS item (folder, feed, etc). (alias: rss_moveItem)

Raises:	Conflict409Error –
Parameters:	orig_item_path – path to item to be removed (e.g. FolderSubfolderItemName) new_item_path – path to item to be removed (e.g. FolderSubfolderItemName)
Returns:	None

rss_refreshItem(item_path=None, **kwargs)¶

Trigger a refresh for a RSS item (alias: rss_refreshItem)

Parameters:	item_path – path to item to be refreshed (e.g. FolderSubfolderItemName)
Returns:	None

rss_refresh_item(item_path=None, **kwargs)¶

Trigger a refresh for a RSS item (alias: rss_refreshItem)

Parameters:	item_path – path to item to be refreshed (e.g. FolderSubfolderItemName)
Returns:	None

rss_removeItem(item_path=None, **kwargs)¶

Remove a RSS item (folder, feed, etc). (alias: rss_removeItem)

NOTE: Removing a folder also removes everything in it.

Raises:	Conflict409Error –
Parameters:	item_path – path to item to be removed (e.g. FolderSubfolderItemName)
Returns:	None

rss_removeRule(rule_name=None, **kwargs)¶

Delete a RSS auto-downloading rule. (alias: rss_removeRule)

Parameters:	rule_name – Name of rule to delete
Returns:	None

rss_remove_item(item_path=None, **kwargs)¶

Remove a RSS item (folder, feed, etc). (alias: rss_removeItem)

NOTE: Removing a folder also removes everything in it.

Raises:	Conflict409Error –
Parameters:	item_path – path to item to be removed (e.g. FolderSubfolderItemName)
Returns:	None

rss_remove_rule(rule_name=None, **kwargs)¶

Delete a RSS auto-downloading rule. (alias: rss_removeRule)

Parameters:	rule_name – Name of rule to delete
Returns:	None

rss_renameRule(orig_rule_name=None, new_rule_name=None, **kwargs)¶

Rename a RSS auto-download rule. (alias: rss_renameRule) Note: this endpoint did not work properly until qBittorrent v4.3.0

Parameters:	orig_rule_name – current name of rule new_rule_name – new name for rule
Returns:	None

rss_rename_rule(orig_rule_name=None, new_rule_name=None, **kwargs)¶

Rename a RSS auto-download rule. (alias: rss_renameRule) Note: this endpoint did not work properly until qBittorrent v4.3.0

Parameters:	orig_rule_name – current name of rule new_rule_name – new name for rule
Returns:	None

rss_rules(**kwargs)¶

Retrieve RSS auto-download rule definitions.

Returns:	None

rss_setRule(rule_name=None, rule_def=None, **kwargs)¶

Create a new RSS auto-downloading rule. (alias: rss_setRule)

Parameters:	rule_name – name for new rule rule_def – dictionary with rule fields Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#set-auto-downloading-rule
Returns:	None

rss_set_rule(rule_name=None, rule_def=None, **kwargs)¶

Create a new RSS auto-downloading rule. (alias: rss_setRule)

Parameters:	rule_name – name for new rule rule_def – dictionary with rule fields Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#set-auto-downloading-rule
Returns:	None

class qbittorrentapi.RSS(client)¶

Allows interaction with “RSS” API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host='localhost:8080', username='admin', password='adminadmin')
>>> # this is all the same attributes that are available as named in the
>>> #  endpoints or the more pythonic names in Client (with or without 'log_' prepended)
>>> rss_rules = client.rss.rules
>>> client.rss.addFolder(folder_path="TPB")
>>> client.rss.addFeed(url='...', item_path="TPB\Top100")
>>> client.rss.remove_item(item_path="TPB") # deletes TPB and Top100
>>> client.rss.set_rule(rule_name="...", rule_def={...})
>>> client.rss.items.with_data
>>> client.rss.items.without_data

addFeed(url=None, item_path=None, **kwargs)¶

addFolder(folder_path=None, **kwargs)¶

add_feed(url=None, item_path=None, **kwargs)¶

add_folder(folder_path=None, **kwargs)¶

markAsRead(item_path=None, article_id=None, **kwargs)¶

mark_as_read(item_path=None, article_id=None, **kwargs)¶

matchingArticles(rule_name=None, **kwargs)¶

matching_articles(rule_name=None, **kwargs)¶

moveItem(orig_item_path=None, new_item_path=None, **kwargs)¶

move_item(orig_item_path=None, new_item_path=None, **kwargs)¶

refreshItem(item_path=None)¶

refresh_item(item_path=None)¶

removeItem(item_path=None, **kwargs)¶

removeRule(rule_name=None, **kwargs)¶

remove_item(item_path=None, **kwargs)¶

remove_rule(rule_name=None, **kwargs)¶

renameRule(orig_rule_name=None, new_rule_name=None, **kwargs)¶

rename_rule(orig_rule_name=None, new_rule_name=None, **kwargs)¶

rules¶

setRule(rule_name=None, rule_def=None, **kwargs)¶

set_rule(rule_name=None, rule_def=None, **kwargs)¶

Search¶

class qbittorrentapi.SearchAPIMixIn(host='', port=None, username=None, password=None, **kwargs)¶

Implementation for all Search API methods.

search_categories(plugin_name=None, **kwargs)¶

Retrieve categories for search. Note: endpoint was removed in qBittorrent v4.3.0

Parameters:	plugin_name – Limit categories returned by plugin(s) (supports ‘all’ and ‘enabled’)
Returns:	list of categories

search_delete(search_id=None, **kwargs)¶

Delete a search job.

Raises:	NotFound404Error –
Parameters:	search_id – ID of search to delete
Returns:	None

search_enablePlugin(plugins=None, enable=None, **kwargs)¶

Enable or disable search plugin(s). (alias: search_enablePlugin)

Parameters:	plugins – list of plugin names enable – True or False
Returns:	None

search_enable_plugin(plugins=None, enable=None, **kwargs)¶

Enable or disable search plugin(s). (alias: search_enablePlugin)

Parameters:	plugins – list of plugin names enable – True or False
Returns:	None

search_installPlugin(sources=None, **kwargs)¶

Install search plugins from either URL or file. (alias: search_installPlugin)

Parameters:	sources – list of URLs or filepaths
Returns:	None

search_install_plugin(sources=None, **kwargs)¶

Install search plugins from either URL or file. (alias: search_installPlugin)

Parameters:	sources – list of URLs or filepaths
Returns:	None

search_plugins(**kwargs)¶

Retrieve details of search plugins.

Returns:	List of plugins. Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-search-plugins

search_results(search_id=None, limit=None, offset=None, **kwargs)¶

Retrieve the results for the search.

Raises:	NotFound404Error – Conflict409Error –
Parameters:	search_id – ID of search job limit – number of results to return offset – where to start returning results
Returns:	Dictionary of results Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-search-results

search_start(pattern=None, plugins=None, category=None, **kwargs)¶

Start a search. Python must be installed. Host may limit number of concurrent searches.

Raises:	Conflict409Error –
Parameters:	pattern – term to search for plugins – list of plugins to use for searching (supports ‘all’ and ‘enabled’) category – categories to limit search; dependent on plugins. (supports ‘all’)
Returns:	search job

search_status(search_id=None, **kwargs)¶

Retrieve status of one or all searches.

Raises:	NotFound404Error –
Parameters:	search_id – ID of search to get status; leave emtpy for status of all jobs
Returns:	dictionary of searches Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-search-status

search_stop(search_id=None, **kwargs)¶

Stop a running search.

Raises:	NotFound404Error –
Parameters:	search_id – ID of search job to stop
Returns:	None

search_uninstallPlugin(names=None, **kwargs)¶

Uninstall search plugins. (alias: search_uninstallPlugin)

Parameters:	names – names of plugins to uninstall
Returns:	None

search_uninstall_plugin(names=None, **kwargs)¶

Uninstall search plugins. (alias: search_uninstallPlugin)

Parameters:	names – names of plugins to uninstall
Returns:	None

search_updatePlugins(**kwargs)¶

Auto update search plugins. (alias: search_updatePlugins)

Returns:	None

search_update_plugins(**kwargs)¶

Auto update search plugins. (alias: search_updatePlugins)

Returns:	None

class qbittorrentapi.Search(*args, **kwargs)¶

Allows interaction with “Search” API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host='localhost:8080', username='admin', password='adminadmin')
>>> # this is all the same attributes that are available as named in the
>>> #  endpoints or the more pythonic names in Client (with or without 'search_' prepended)
>>> # initiate searches and retrieve results
>>> search_job = client.search.start(pattern='Ubuntu', plugins='all', category='all')
>>> status = search_job.status()
>>> results = search_job.result()
>>> search_job.delete()
>>> # inspect and manage plugins
>>> plugins = client.search.plugins
>>> cats = client.search.categories(plugin_name='...')
>>> client.search.install_plugin(sources='...')
>>> client.search.update_plugins()

categories(plugin_name=None, **kwargs)¶

delete(search_id=None, **kwargs)¶

enablePlugin(plugins=None, enable=None, **kwargs)¶

enable_plugin(plugins=None, enable=None, **kwargs)¶

installPlugin(sources=None, **kwargs)¶

install_plugin(sources=None, **kwargs)¶

plugins¶

results(search_id=None, limit=None, offset=None, **kwargs)¶

start(pattern=None, plugins=None, category=None, **kwargs)¶

status(search_id=None, **kwargs)¶

stop(search_id=None, **kwargs)¶

uninstallPlugin(sources=None, **kwargs)¶

uninstall_plugin(sources=None, **kwargs)¶

updatePlugins(**kwargs)¶

update_plugins(**kwargs)¶

Sync¶

class qbittorrentapi.SyncAPIMixIn(host='', port=None, username=None, password=None, **kwargs)¶

Implementation of all Sync API Methods.

sync_maindata(rid=0, **kwargs)¶

Retrieves sync data.

Parameters:	rid – response ID
Returns:	dictionary response Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-main-data

sync_torrentPeers(torrent_hash=None, rid=0, **kwargs)¶

Retrieves torrent sync data. (alias: sync_torrentPeers)

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent rid – response ID
Returns:	Dictionary of torrent sync data. Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-peers-data

sync_torrent_peers(torrent_hash=None, rid=0, **kwargs)¶

Retrieves torrent sync data. (alias: sync_torrentPeers)

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent rid – response ID
Returns:	Dictionary of torrent sync data. Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-peers-data

class qbittorrentapi.Sync(client)¶

Alows interaction with the “Sync” API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host='localhost:8080', username='admin', password='adminadmin')
>>> # this are all the same attributes that are available as named in the
>>> #  endpoints or the more pythonic names in Client (with or without 'sync_' prepended)
>>> maindata = client.sync.maindata(rid="...")
>>> # for use when continuously calling maindata for changes in torrents
>>> # this will automatically request the changes since the last call
>>> md = client.sync.maindata.delta()
>>> #
>>> torrentPeers= client.sync.torrentPeers(hash="...'", rid='...')
>>> torrent_peers = client.sync.torrent_peers(hash="...'", rid='...')

Torrent States¶

class qbittorrentapi.TorrentStates¶

Torrent States as defined by qBittorrent.

Definitions:

wiki: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-list
code: https://github.com/qbittorrent/qBittorrent/blob/master/src/base/bittorrent/torrenthandle.h#L52

Usage:

>>> from qbittorrentapi import Client
>>> from qbittorrentapi import TorrentStates
>>> client = Client()
>>> # print torrent hashes for torrents that are downloading
>>> for torrent in client.torrents_info():
>>>     # check if torrent is downloading
>>>     if torrent.state_enum.is_downloading:
>>>         print(f'{torrent.hash} is downloading...')
>>>     # the appropriate enum member can be directly derived
>>>     state_enum = TorrentStates(torrent.state)
>>>     print(f'{torrent.hash}: {state_enum.value}')

ALLOCATING = 'allocating'¶

CHECKING_DOWNLOAD = 'checkingDL'¶

CHECKING_RESUME_DATA = 'checkingResumeData'¶

CHECKING_UPLOAD = 'checkingUP'¶

DOWNLOADING = 'downloading'¶

ERROR = 'error'¶

FORCED_UPLOAD = 'forcedUP'¶

FORCE_DOWNLOAD = 'forceDL'¶

METADATA_DOWNLOAD = 'metaDL'¶

MISSING_FILES = 'missingFiles'¶

MOVING = 'moving'¶

PAUSED_DOWNLOAD = 'pausedDL'¶

PAUSED_UPLOAD = 'pausedUP'¶

QUEUED_DOWNLOAD = 'queuedDL'¶

QUEUED_UPLOAD = 'queuedUP'¶

STALLED_DOWNLOAD = 'stalledDL'¶

STALLED_UPLOAD = 'stalledUP'¶

UNKNOWN = 'unknown'¶

UPLOADING = 'uploading'¶

is_checking¶: Returns True if the State is categorized as Checking.

is_complete¶: Returns True if the State is categorized as Complete.

is_downloading¶: Returns True if the State is categorized as Downloading.

is_errored¶: Returns True if the State is categorized as Errored.

is_paused¶: Returns True if the State is categorized as Paused.

is_uploading¶: Returns True if the State is categorized as Uploading.

Torrents¶

class qbittorrentapi.TorrentsAPIMixIn(host='', port=None, username=None, password=None, **kwargs)¶

Implementation of all Torrents API methods.

torrents_add(urls=None, torrent_files=None, save_path=None, cookie=None, category=None, is_skip_checking=None, is_paused=None, is_root_folder=None, rename=None, upload_limit=None, download_limit=None, use_auto_torrent_management=None, is_sequential_download=None, is_first_last_piece_priority=None, **kwargs)¶

Add one or more torrents by URLs and/or torrent files.

Raises:	UnsupportedMediaType415Error – if file is not a valid torrent file TorrentFileNotFoundError – if a torrent file doesn’t exist TorrentFilePermissionError – if read permission is denied to torrent file
Parameters:	urls – single instance or an iterable of URLs (http://, https://, magnet: and bc://bt/) torrent_files – several options are available to send torrent files to qBittorrent: 1) single instance of bytes: useful if torrent file already read from disk or downloaded from internet. 2) single instance of file handle to torrent file: use open(<filepath>, ‘rb’) to open the torrent file. 3) single instance of a filepath to torrent file: e.g. ‘/home/user/torrent_filename.torrent’ 4) an iterable of the single instances above to send more than one torrent file 5) dictionary with key/value pairs of torrent name and single instance of above object Note: The torrent name in a dictionary is useful to identify which torrent file errored. qBittorrent provides back that name in the error text. If a torrent name is not provided, then the name of the file will be used. And in the case of bytes (or if filename cannot be determined), the value ‘torrent__n’ will be used save_path – location to save the torrent data cookie – cookie to retrieve torrents by URL category – category to assign to torrent(s) is_skip_checking – skip hash checking is_paused – True to start torrent(s) paused is_root_folder – True or False to create root folder rename – new name for torrent(s) upload_limit – upload limit in bytes/second download_limit – download limit in bytes/second use_auto_torrent_management – True or False to use automatic torrent management is_sequential_download – True or False for sequential download is_first_last_piece_priority – True or False for first and last piece download priority
Returns:	“Ok.” for success and “Fails.” for failure

torrents_addPeers(peers=None, torrent_hashes=None, **kwargs)¶

Add one or more peers to one or more torrents. (alias: torrents_addPeers)

Raises:	InvalidRequest400Error – for invalid peers
Parameters:	peers – one or more peers to add. each peer should take the form ‘host:port’ torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	dictionary - {<hash>: {‘added’: #, ‘failed’: #}}

torrents_addTags(tags=None, torrent_hashes=None, **kwargs)¶

Add one or more tags to one or more torrents. (alias: torrents_addTags) Note: Tags that do not exist will be created on-the-fly.

Parameters:	tags – tag name or list of tags torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_addTrackers(torrent_hash=None, urls=None, **kwargs)¶

Add trackers to a torrent. (alias: torrents_addTrackers)

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent urls – tracker urls to add to torrent
Returns:	None

torrents_add_peers(peers=None, torrent_hashes=None, **kwargs)¶

Add one or more peers to one or more torrents. (alias: torrents_addPeers)

Raises:	InvalidRequest400Error – for invalid peers
Parameters:	peers – one or more peers to add. each peer should take the form ‘host:port’ torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	dictionary - {<hash>: {‘added’: #, ‘failed’: #}}

torrents_add_tags(tags=None, torrent_hashes=None, **kwargs)¶

Add one or more tags to one or more torrents. (alias: torrents_addTags) Note: Tags that do not exist will be created on-the-fly.

Parameters:	tags – tag name or list of tags torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_add_trackers(torrent_hash=None, urls=None, **kwargs)¶

Add trackers to a torrent. (alias: torrents_addTrackers)

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent urls – tracker urls to add to torrent
Returns:	None

torrents_bottomPrio(torrent_hashes=None, **kwargs)¶

Set torrent as highest priority. Torrent Queuing must be enabled. (alias: torrents_bottomPrio)

Raises:	Conflict409 –
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_bottom_priority(torrent_hashes=None, **kwargs)¶

Set torrent as highest priority. Torrent Queuing must be enabled. (alias: torrents_bottomPrio)

Raises:	Conflict409 –
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_categories(**kwargs)¶

Retrieve all category definitions

Note: torrents/categories is not available until v2.1.0 :return: dictionary of categories

torrents_createCategory(name=None, save_path=None, **kwargs)¶

Create a new torrent category. (alias: torrents_createCategory)

Note: save_path is not available until web API version 2.1.0

Raises:	Conflict409 – if category name is not valid or unable to create
Parameters:	name – name for new category save_path – location to save torrents for this category
Returns:	None

torrents_createTags(tags=None, **kwargs)¶

Create one or more tags. (alias: torrents_createTags)

Parameters:	tags – tag name or list of tags
Returns:	None

torrents_create_category(name=None, save_path=None, **kwargs)¶

Create a new torrent category. (alias: torrents_createCategory)

Note: save_path is not available until web API version 2.1.0

Raises:	Conflict409 – if category name is not valid or unable to create
Parameters:	name – name for new category save_path – location to save torrents for this category
Returns:	None

torrents_create_tags(tags=None, **kwargs)¶

Create one or more tags. (alias: torrents_createTags)

Parameters:	tags – tag name or list of tags
Returns:	None

torrents_decreasePrio(torrent_hashes=None, **kwargs)¶

Decrease the priority of a torrent. Torrent Queuing must be enabled. (alias: torrents_decreasePrio)

Raises:	Conflict409 –
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_decrease_priority(torrent_hashes=None, **kwargs)¶

Decrease the priority of a torrent. Torrent Queuing must be enabled. (alias: torrents_decreasePrio)

Raises:	Conflict409 –
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_delete(delete_files=None, torrent_hashes=None, **kwargs)¶

Remove a torrent from qBittorrent and optionally delete its files.

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. delete_files – True to delete the torrent’s files
Returns:	None

torrents_deleteTags(tags=None, **kwargs)¶

Delete one or more tags. (alias: torrents_deleteTags)

Parameters:	tags – tag name or list of tags
Returns:	None

torrents_delete_tags(tags=None, **kwargs)¶

Delete one or more tags. (alias: torrents_deleteTags)

Parameters:	tags – tag name or list of tags
Returns:	None

torrents_downloadLimit(torrent_hashes=None, **kwargs)¶

Retrieve the download limit for one or more torrents. (alias: torrents_downloadLimit)

Returns:	dictioanry {hash: limit} (-1 represents no limit)

torrents_download_limit(torrent_hashes=None, **kwargs)¶

Retrieve the download limit for one or more torrents. (alias: torrents_downloadLimit)

Returns:	dictioanry {hash: limit} (-1 represents no limit)

torrents_editCategory(name=None, save_path=None, **kwargs)¶

Edit an existing category. (alias: torrents_editCategory)

Note: torrents/editCategory not available until web API version 2.1.0

Raises:	Conflict409 –
Parameters:	name – category to edit save_path – new location to save files for this category
Returns:	None

torrents_editTracker(torrent_hash=None, original_url=None, new_url=None, **kwargs)¶

Replace a torrent’s tracker with a different one. (alias: torrents_editTrackers)

Raises:	InvalidRequest400 – NotFound404Error – Conflict409Error –
Parameters:	torrent_hash – hash for torrent original_url – URL for existing tracker new_url – new URL to replace
Returns:	None

torrents_edit_category(name=None, save_path=None, **kwargs)¶

Edit an existing category. (alias: torrents_editCategory)

Note: torrents/editCategory not available until web API version 2.1.0

Raises:	Conflict409 –
Parameters:	name – category to edit save_path – new location to save files for this category
Returns:	None

torrents_edit_tracker(torrent_hash=None, original_url=None, new_url=None, **kwargs)¶

Replace a torrent’s tracker with a different one. (alias: torrents_editTrackers)

Raises:	InvalidRequest400 – NotFound404Error – Conflict409Error –
Parameters:	torrent_hash – hash for torrent original_url – URL for existing tracker new_url – new URL to replace
Returns:	None

torrents_filePrio(torrent_hash=None, file_ids=None, priority=None, **kwargs)¶

Set priority for one or more files. (alias: torrents_filePrio)

Raises:	InvalidRequest400 – if priority is invalid or at least one file ID is not an integer NotFound404Error – Conflict409 – if torrent metadata has not finished downloading or at least one file was not found
Parameters:	torrent_hash – hash for torrent file_ids – single file ID or a list. priority – priority for file(s) Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#set-file-priority
Returns:	None

torrents_file_priority(torrent_hash=None, file_ids=None, priority=None, **kwargs)¶

Set priority for one or more files. (alias: torrents_filePrio)

Raises:	InvalidRequest400 – if priority is invalid or at least one file ID is not an integer NotFound404Error – Conflict409 – if torrent metadata has not finished downloading or at least one file was not found
Parameters:	torrent_hash – hash for torrent file_ids – single file ID or a list. priority – priority for file(s) Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#set-file-priority
Returns:	None

torrents_files(torrent_hash=None, **kwargs)¶

Retrieve individual torrent’s files.

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent
Returns:	List of torrent’s files Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-contents

torrents_increasePrio(torrent_hashes=None, **kwargs)¶

Increase the priority of a torrent. Torrent Queuing must be enabled. (alias: torrents_increasePrio)

Raises:	Conflict409 –
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_increase_priority(torrent_hashes=None, **kwargs)¶

Increase the priority of a torrent. Torrent Queuing must be enabled. (alias: torrents_increasePrio)

Raises:	Conflict409 –
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_info(status_filter=None, category=None, sort=None, reverse=None, limit=None, offset=None, torrent_hashes=None, **kwargs)¶

Retrieves list of info for torrents. Note: hashes is available starting web API version 2.0.1

Parameters:

status_filter – Filter list by all, downloading, completed, paused, active, inactive, resumed stalled, stalled_uploading and stalled_downloading added in Web API v2.4.1
category – Filter list by category
sort – Sort list by any property returned
reverse – Reverse sorting
limit – Limit length of list
offset – Start of list (if < 0, offset from end of list)
torrent_hashes – Filter list by hash (separate multiple hashes with a ‘|’)

Returns:

List of torrents Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-list

torrents_pause(torrent_hashes=None, **kwargs)¶

Pause one or more torrents in qBittorrent.

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_pieceHashes(torrent_hash=None, **kwargs)¶

Retrieve individual torrent’s pieces’ hashes. (alias: torrents_pieceHashes)

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent
Returns:	List of torrent’s pieces’ hashes

torrents_pieceStates(torrent_hash=None, **kwargs)¶

Retrieve individual torrent’s pieces’ states. (alias: torrents_pieceStates)

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent
Returns:	list of torrent’s pieces’ states

torrents_piece_hashes(torrent_hash=None, **kwargs)¶

Retrieve individual torrent’s pieces’ hashes. (alias: torrents_pieceHashes)

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent
Returns:	List of torrent’s pieces’ hashes

torrents_piece_states(torrent_hash=None, **kwargs)¶

Retrieve individual torrent’s pieces’ states. (alias: torrents_pieceStates)

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent
Returns:	list of torrent’s pieces’ states

torrents_properties(torrent_hash=None, **kwargs)¶

Retrieve individual torrent’s properties.

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent
Returns:	Dictionary of torrent properties Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-generic-properties

torrents_reannounce(torrent_hashes=None, **kwargs)¶

Reannounce a torrent.

Note: torrents/reannounce not available web API version 2.0.2

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_recheck(torrent_hashes=None, **kwargs)¶

Recheck a torrent in qBittorrent.

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_removeCategories(categories=None, **kwargs)¶

Delete one or more categories. (alias: torrents_removeCategories)

Parameters:	categories – categories to delete
Returns:	None

torrents_removeTags(tags=None, torrent_hashes=None, **kwargs)¶

Add one or more tags to one or more torrents. (alias: torrents_removeTags)

Parameters:	tags – tag name or list of tags torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_removeTrackers(torrent_hash=None, urls=None, **kwargs)¶

Remove trackers from a torrent. (alias: torrents_removeTrackers)

Raises:	NotFound404Error – Conflict409Error –
Parameters:	torrent_hash – hash for torrent urls – tracker urls to removed from torrent
Returns:	None

torrents_remove_categories(categories=None, **kwargs)¶

Delete one or more categories. (alias: torrents_removeCategories)

Parameters:	categories – categories to delete
Returns:	None

torrents_remove_tags(tags=None, torrent_hashes=None, **kwargs)¶

Add one or more tags to one or more torrents. (alias: torrents_removeTags)

Parameters:	tags – tag name or list of tags torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_remove_trackers(torrent_hash=None, urls=None, **kwargs)¶

Remove trackers from a torrent. (alias: torrents_removeTrackers)

Raises:	NotFound404Error – Conflict409Error –
Parameters:	torrent_hash – hash for torrent urls – tracker urls to removed from torrent
Returns:	None

torrents_rename(torrent_hash=None, new_torrent_name=None, **kwargs)¶

Rename a torrent.

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent new_torrent_name – new name for torrent
Returns:	None

torrents_renameFile(torrent_hash=None, file_id=None, new_file_name=None, **kwargs)¶

Rename a torrent file.

Raises:	MissingRequiredParameters400Error – NotFound404Error – Conflict409Error –
Parameters:	torrent_hash – hash for torrent file_id – id for file new_file_name – new name for file
Returns:	None

torrents_rename_file(torrent_hash=None, file_id=None, new_file_name=None, **kwargs)¶

Rename a torrent file.

Raises:	MissingRequiredParameters400Error – NotFound404Error – Conflict409Error –
Parameters:	torrent_hash – hash for torrent file_id – id for file new_file_name – new name for file
Returns:	None

torrents_resume(torrent_hashes=None, **kwargs)¶

Resume one or more torrents in qBittorrent.

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_setAutoManagement(enable=None, torrent_hashes=None, **kwargs)¶

Enable or disable automatic torrent management for one or more torrents. (alias: torrents_setAutoManagement)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. enable – True or False
Returns:	None

torrents_setCategory(category=None, torrent_hashes=None, **kwargs)¶

Set a category for one or more torrents. (alias: torrents_setCategory)

Raises:	Conflict409 – for bad category
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. category – category to assign to torrent
Returns:	None

torrents_setDownloadLimit(limit=None, torrent_hashes=None, **kwargs)¶

Set the download limit for one or more torrents. (alias: torrents_setDownloadLimit)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. limit – bytes/second (-1 sets the limit to infinity)
Returns:	None

torrents_setForceStart(enable=None, torrent_hashes=None, **kwargs)¶

Force start one or more torrents. (alias: torrents_setForceStart)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. enable – True or False (False makes this equivalent to torrents_resume())
Returns:	None

torrents_setLocation(location=None, torrent_hashes=None, **kwargs)¶

Set location for torrents’s files. (alias: torrents_setLocation)

Raises:	Forbidden403Error – if the user doesn’t have permissions to write to the location Conflict409 – if the directory cannot be created at the location
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. location – disk location to move torrent’s files
Returns:	None

torrents_setShareLimits(ratio_limit=None, seeding_time_limit=None, torrent_hashes=None, **kwargs)¶

Set share limits for one or more torrents.

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. ratio_limit – max ratio to seed a torrent. (-2 means use the global value and -1 is no limit) seeding_time_limit – minutes (-2 means use the global value and -1 is no limit)
Returns:	None

torrents_setSuperSeeding(enable=None, torrent_hashes=None, **kwargs)¶

Set one or more torrents as super seeding. (alias: torrents_setSuperSeeding)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. enable – True or False
Returns:

torrents_setUploadLimit(limit=None, torrent_hashes=None, **kwargs)¶

Set the upload limit for one or more torrents. (alias: torrents_setUploadLimit)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. limit – bytes/second (-1 sets the limit to infinity)
Returns:	None

torrents_set_auto_management(enable=None, torrent_hashes=None, **kwargs)¶

Enable or disable automatic torrent management for one or more torrents. (alias: torrents_setAutoManagement)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. enable – True or False
Returns:	None

torrents_set_category(category=None, torrent_hashes=None, **kwargs)¶

Set a category for one or more torrents. (alias: torrents_setCategory)

Raises:	Conflict409 – for bad category
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. category – category to assign to torrent
Returns:	None

torrents_set_download_limit(limit=None, torrent_hashes=None, **kwargs)¶

Set the download limit for one or more torrents. (alias: torrents_setDownloadLimit)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. limit – bytes/second (-1 sets the limit to infinity)
Returns:	None

torrents_set_force_start(enable=None, torrent_hashes=None, **kwargs)¶

Force start one or more torrents. (alias: torrents_setForceStart)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. enable – True or False (False makes this equivalent to torrents_resume())
Returns:	None

torrents_set_location(location=None, torrent_hashes=None, **kwargs)¶

Set location for torrents’s files. (alias: torrents_setLocation)

Raises:	Forbidden403Error – if the user doesn’t have permissions to write to the location Conflict409 – if the directory cannot be created at the location
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. location – disk location to move torrent’s files
Returns:	None

torrents_set_share_limits(ratio_limit=None, seeding_time_limit=None, torrent_hashes=None, **kwargs)¶

Set share limits for one or more torrents.

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. ratio_limit – max ratio to seed a torrent. (-2 means use the global value and -1 is no limit) seeding_time_limit – minutes (-2 means use the global value and -1 is no limit)
Returns:	None

torrents_set_super_seeding(enable=None, torrent_hashes=None, **kwargs)¶

Set one or more torrents as super seeding. (alias: torrents_setSuperSeeding)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. enable – True or False
Returns:

torrents_set_upload_limit(limit=None, torrent_hashes=None, **kwargs)¶

Set the upload limit for one or more torrents. (alias: torrents_setUploadLimit)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents. limit – bytes/second (-1 sets the limit to infinity)
Returns:	None

torrents_tags(**kwargs)¶

Retrieve all tag definitions.

Returns:	list of tags

torrents_toggleFirstLastPiecePrio(torrent_hashes=None, **kwargs)¶

Toggle priority of first/last piece downloading. (alias: torrents_toggleFirstLastPiecePrio)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_toggleSequentialDownload(torrent_hashes=None, **kwargs)¶

Toggle sequential download for one or more torrents. (alias: torrents_toggleSequentialDownload)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_toggle_first_last_piece_priority(torrent_hashes=None, **kwargs)¶

Toggle priority of first/last piece downloading. (alias: torrents_toggleFirstLastPiecePrio)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_toggle_sequential_download(torrent_hashes=None, **kwargs)¶

Toggle sequential download for one or more torrents. (alias: torrents_toggleSequentialDownload)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_topPrio(torrent_hashes=None, **kwargs)¶

Set torrent as highest priority. Torrent Queuing must be enabled. (alias: torrents_topPrio)

Raises:	Conflict409 –
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_top_priority(torrent_hashes=None, **kwargs)¶

Set torrent as highest priority. Torrent Queuing must be enabled. (alias: torrents_topPrio)

Raises:	Conflict409 –
Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	None

torrents_trackers(torrent_hash=None, **kwargs)¶

Retrieve individual torrent’s trackers.

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent
Returns:	List of torrent’s trackers Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-trackers

torrents_uploadLimit(torrent_hashes=None, **kwargs)¶

Retrieve the upload limit for one or more torrents. (alias: torrents_uploadLimit)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	dictionary of limits

torrents_upload_limit(torrent_hashes=None, **kwargs)¶

Retrieve the upload limit for one or more torrents. (alias: torrents_uploadLimit)

Parameters:	torrent_hashes – single torrent hash or list of torrent hashes. Or ‘all’ for all torrents.
Returns:	dictionary of limits

torrents_webseeds(torrent_hash=None, **kwargs)¶

Retrieve individual torrent’s web seeds.

Raises:	NotFound404Error –
Parameters:	torrent_hash – hash for torrent
Returns:	List of torrent’s web seeds Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-torrent-web-seeds

class qbittorrentapi.Torrents(client)¶

Allows interaction with the “Torrents” API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host='localhost:8080', username='admin', password='adminadmin')
>>> # this are all the same attributes that are available as named in the
>>> #  endpoints or the more pythonic names in Client (with or without 'torrents_' prepended)
>>> torrent_list = client.torrents.info()
>>> torrent_list_active = client.torrents.info.active()
>>> torrent_list_active_partial = client.torrents.info.active(limit=100, offset=200)
>>> torrent_list_downloading = client.torrents.info.downloading()
>>> # torrent looping
>>> for torrent in client.torrents.info.completed()
>>> # all torrents endpoints with a 'hashes' parameters support all method to apply action to all torrents
>>> client.torrents.pause.all()
>>> client.torrents.resume.all()
>>> # or specify the individual hashes
>>> client.torrents.downloadLimit(torrent_hashes=['...', '...'])

add(urls=None, torrent_files=None, save_path=None, cookie=None, category=None, is_skip_checking=None, is_paused=None, is_root_folder=None, rename=None, upload_limit=None, download_limit=None, use_auto_torrent_management=None, is_sequential_download=None, is_first_last_piece_priority=None, **kwargs)¶

class qbittorrentapi.TorrentDictionary(data, client)¶

Alows interaction with individual torrents via the “Torrents” API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host='localhost:8080', username='admin', password='adminadmin')
>>> # this are all the same attributes that are available as named in the
>>> #  endpoints or the more pythonic names in Client (with or without 'transfer_' prepended)
>>> torrent = client.torrents.info()[0]
>>> torrent_hash = torrent.info.hash
>>> # Attributes without inputs and a return value are properties
>>> properties = torrent.properties
>>> trackers = torrent.trackers
>>> files = torrent.files
>>> # Action methods
>>> torrent.edit_tracker(original_url="...", new_url="...")
>>> torrent.remove_trackers(urls='http://127.0.0.2/')
>>> torrent.rename(new_torrent_name="...")
>>> torrent.resume()
>>> torrent.pause()
>>> torrent.recheck()
>>> torrent.torrents_top_priority()
>>> torrent.setLocation(location='/home/user/torrents/')
>>> torrent.setCategory(category='video')

addTags(tags=None, **kwargs)¶

addTrackers(urls=None, **kwargs)¶

add_tags(tags=None, **kwargs)¶

add_trackers(urls=None, **kwargs)¶

bottomPrio(**kwargs)¶

bottom_priority(**kwargs)¶

decreasePrio(**kwargs)¶

decrease_priority(**kwargs)¶

delete(delete_files=None, **kwargs)¶

downloadLimit¶

download_limit¶

editTracker(orig_url=None, new_url=None, **kwargs)¶

edit_tracker(orig_url=None, new_url=None, **kwargs)¶

filePriority(file_ids=None, priority=None, **kwargs)¶

file_priority(file_ids=None, priority=None, **kwargs)¶

files¶

increasePrio(**kwargs)¶

increase_priority(**kwargs)¶

info¶

pause(**kwargs)¶

pieceHashes¶

pieceStates¶

piece_hashes¶

piece_states¶

properties¶

reannounce(**kwargs)¶

recheck(**kwargs)¶

removeTags(tags=None, **kwargs)¶

removeTrackers(urls=None, **kwargs)¶

remove_tags(tags=None, **kwargs)¶

remove_trackers(urls=None, **kwargs)¶

rename(new_name=None, **kwargs)¶

renameFile(file_id=None, new_file_name=None, **kwargs)¶

rename_file(file_id=None, new_file_name=None, **kwargs)¶

resume(**kwargs)¶

setAutoManagement(enable=None, **kwargs)¶

setCategory(category=None, **kwargs)¶

setDownloadLimit(limit=None, **kwargs)¶

setForceStart(enable=None, **kwargs)¶

setLocation(location=None, **kwargs)¶

setShareLimits(ratio_limit=None, seeding_time_limit=None, **kwargs)¶

setSuperSeeding(enable=None, **kwargs)¶

setUploadLimit(limit=None, **kwargs)¶

set_auto_management(enable=None, **kwargs)¶

set_category(category=None, **kwargs)¶

set_download_limit(limit=None, **kwargs)¶

set_force_start(enable=None, **kwargs)¶

set_location(location=None, **kwargs)¶

set_share_limits(ratio_limit=None, seeding_time_limit=None, **kwargs)¶

set_super_seeding(enable=None, **kwargs)¶

set_upload_limit(limit=None, **kwargs)¶

state_enum¶: Returns the formalized Enumeration for Torrent State instead of the raw string.

sync_local()¶: Update local cache of torrent info.

toggleFirstLastPiecePrio(**kwargs)¶

toggleSequentialDownload(**kwargs)¶

toggle_first_last_piece_priority(**kwargs)¶

toggle_sequential_download(**kwargs)¶

topPrio(**kwargs)¶

top_priority(**kwargs)¶

trackers¶

uploadLimit¶

upload_limit¶

webseeds¶

Transfer¶

class qbittorrentapi.TransferAPIMixIn(host='', port=None, username=None, password=None, **kwargs)¶

Implementation of all Transfer API methods

transfer_banPeers(peers=None, **kwargs)¶

Ban one or more peers. (alias: transfer_banPeers)

Parameters:	peers – one or more peers to ban. each peer should take the form ‘host:port’
Returns:	None

transfer_ban_peers(peers=None, **kwargs)¶

Ban one or more peers. (alias: transfer_banPeers)

Parameters:	peers – one or more peers to ban. each peer should take the form ‘host:port’
Returns:	None

transfer_downloadLimit(**kwargs)¶

Retrieves download limit. 0 is unlimited. (alias: transfer_downloadLimit)

Returns:	integer

transfer_download_limit(**kwargs)¶

Retrieves download limit. 0 is unlimited. (alias: transfer_downloadLimit)

Returns:	integer

transfer_info(**kwargs)¶

Retrieves the global transfer info usually found in qBittorrent status bar.

Returns:	dictionary of status items Properties: https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-4.1)#get-global-transfer-info

transfer_setDownloadLimit(limit=None, **kwargs)¶

Set the global download limit in bytes/second. (alias: transfer_setDownloadLimit)

Parameters:	limit – download limit in bytes/second (0 or -1 for no limit)
Returns:	None

transfer_setUploadLimit(limit=None, **kwargs)¶

Set the global download limit in bytes/second. (alias: transfer_setUploadLimit)

Parameters:	limit – upload limit in bytes/second (0 or -1 for no limit)
Returns:	None

transfer_set_download_limit(limit=None, **kwargs)¶

Set the global download limit in bytes/second. (alias: transfer_setDownloadLimit)

Parameters:	limit – download limit in bytes/second (0 or -1 for no limit)
Returns:	None

transfer_set_upload_limit(limit=None, **kwargs)¶

Set the global download limit in bytes/second. (alias: transfer_setUploadLimit)

Parameters:	limit – upload limit in bytes/second (0 or -1 for no limit)
Returns:	None

transfer_speedLimitsMode(**kwargs)¶

Retrieves whether alternative speed limits are enabled. (alias: transfer_speedLimitMode)

Returns:	‘1’ if alternative speed limits are currently enabled, ‘0’ otherwise

transfer_speed_limits_mode(**kwargs)¶

Retrieves whether alternative speed limits are enabled. (alias: transfer_speedLimitMode)

Returns:	‘1’ if alternative speed limits are currently enabled, ‘0’ otherwise

transfer_toggleSpeedLimitsMode(intended_state=None, **kwargs)¶

Sets whether alternative speed limits are enabled. (alias: transfer_toggleSpeedLimitsMode)

Parameters:	intended_state – True to enable alt speed and False to disable. Leaving None will toggle the current state.
Returns:	None

transfer_toggle_speed_limits_mode(intended_state=None, **kwargs)¶

Sets whether alternative speed limits are enabled. (alias: transfer_toggleSpeedLimitsMode)

Parameters:	intended_state – True to enable alt speed and False to disable. Leaving None will toggle the current state.
Returns:	None

transfer_uploadLimit(**kwargs)¶

Retrieves upload limit. 0 is unlimited. (alias: transfer_uploadLimit)

Returns:	integer

transfer_upload_limit(**kwargs)¶

Retrieves upload limit. 0 is unlimited. (alias: transfer_uploadLimit)

Returns:	integer

class qbittorrentapi.Transfer(*args, **kwargs)¶

Alows interaction with the “Transfer” API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host='localhost:8080', username='admin', password='adminadmin')
>>> # this are all the same attributes that are available as named in the
>>> #  endpoints or the more pythonic names in Client (with or without 'transfer_' prepended)
>>> transfer_info = client.transfer.info
>>> # access and set download/upload limits as attributes
>>> dl_limit = client.transfer.download_limit
>>> # this updates qBittorrent in real-time
>>> client.transfer.download_limit = 1024000
>>> # update speed limits mode to alternate or not
>>> client.transfer.speedLimitsMode = True

banPeers(peers=None, **kwargs)¶

ban_peers(peers=None, **kwargs)¶

downloadLimit¶

download_limit¶

info¶

setDownloadLimit(limit=None, **kwargs)¶

setUploadLimit(limit=None, **kwargs)¶

set_download_limit(limit=None, **kwargs)¶

set_upload_limit(limit=None, **kwargs)¶

speedLimitsMode¶

speed_limits_mode¶

toggleSpeedLimitsMode(intended_state=None, **kwargs)¶

toggle_speed_limits_mode(intended_state=None, **kwargs)¶

uploadLimit¶

upload_limit¶