Torrents¶

class TorrentsAPIMixIn(host=None, port=None, username=None, password=None, api_key=None, EXTRA_HEADERS=None, REQUESTS_ARGS=None, HTTPADAPTER_ARGS=None, VERIFY_WEBUI_CERTIFICATE=True, FORCE_SCHEME_FROM_HOST=False, RAISE_NOTIMPLEMENTEDERROR_FOR_UNIMPLEMENTED_API_ENDPOINTS=False, RAISE_ERROR_FOR_UNSUPPORTED_QBITTORRENT_VERSIONS=False, VERBOSE_RESPONSE_LOGGING=False, SIMPLE_RESPONSES=False, DISABLE_LOGGING_DEBUG_OUTPUT=False) → None¶

Bases: AppAPIMixIn

Implementation of all Torrents API methods.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host="localhost:8080", username="admin", password="adminadmin")
>>> client.torrents_add(urls="...")
>>> client.torrents_reannounce()

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, tags=None, content_layout=None, ratio_limit=None, seeding_time_limit=None, download_path=None, use_download_path=None, stop_condition=None, add_to_top_of_queue=None, inactive_seeding_time_limit=None, share_limit_action=None, ssl_certificate=None, ssl_private_key=None, ssl_dh_params=None, is_stopped=None, forced=None, **kwargs) → str | TorrentsAddedMetadata¶

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

Returns Ok. for success and Fails. for failure.

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
Conflict409Error – torrent is already added to qBittorrent

Parameters:

urls (str | Iterable[str] | None) – single instance or an iterable of URLs (http://, https://, magnet:, bc://bt/)
torrent_files (TypeVar(TorrentFilesT, bytes, str, IO[bytes], Mapping[str, bytes | str | IO[bytes]], Iterable[bytes | str | IO[bytes]]) | None) –
several options are available to send torrent files to qBittorrent:
- single instance of bytes: useful if torrent file already read from disk or downloaded from internet.
- single instance of file handle to torrent file: use open(<filepath>, 'rb') to open the torrent file.
- single instance of a filepath to torrent file: e.g. /home/user/torrent_filename.torrent
- an iterable of the single instances above to send more than one torrent file
- 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 (str | None) – location to save the torrent data
cookie (str | None) – cookie(s) to retrieve torrents by URL
category (str | None) – category to assign to torrent(s)
is_skip_checking (bool | None) – True to skip hash checking
is_paused (bool | None) – Adds torrent in stopped state; alias for is_stopped
is_root_folder (bool | None) – True or False to create root folder (superseded by content_layout with v4.3.2)
rename (str | None) – new name for torrent(s)
upload_limit (str | int | None) – upload limit in bytes/second
download_limit (str | int | None) – download limit in bytes/second
use_auto_torrent_management (bool | None) – True or False to use automatic torrent management
is_sequential_download (bool | None) – True or False for sequential download
is_first_last_piece_priority (bool | None) – True or False for first and last piece download priority
tags (str | Iterable[str] | None) – tag(s) to assign to torrent(s) (added in Web API v2.6.2)
content_layout (Literal['Original', 'Subfolder', 'NoSubfolder'] | None) – Original, Subfolder, or NoSubfolder to control filesystem structure for content (added in Web API v2.7)
ratio_limit (str | float | None) – share limit as ratio of upload amt over download amt; e.g. 0.5 or 2.0 (added in Web API v2.8.1)
seeding_time_limit (str | int | None) – number of minutes to seed torrent (added in Web API v2.8.1)
download_path (str | None) – location to download torrent content before moving to save_path (added in Web API v2.8.4)
use_download_path (bool | None) – True or False whether download_path should be used…defaults to True if download_path is specified (added in Web API v2.8.4)
stop_condition (Literal['MetadataReceived', 'FilesChecked'] | None) – MetadataReceived or FilesChecked to stop the torrent when started automatically (added in Web API v2.8.15)
add_to_top_of_queue (bool | None) – puts torrent at top to the queue(added in Web API v2.8.19)
inactive_seeding_time_limit (str | int | None) – limit for seeding while inactive (added in Web API v2.9.2)
share_limit_action (Literal['Stop', 'Remove', 'RemoveWithContent', 'EnableSuperSeeding'] | None) – override default action when share limit is reached (added in Web API v2.10.4)
ssl_certificate (str | None) – peer certificate (in PEM format) (added in Web API v2.10.4)
ssl_private_key (str | None) – peer private key (added in Web API v2.10.4)
ssl_dh_params (str | None) – Diffie-Hellman parameters (added in Web API v2.10.4)
is_stopped (bool | None) – Adds torrent in stopped state; alias for is_paused (added in Web API v2.11.0)
forced (bool | None) – add torrent in forced state (added in Web API v2.11.0)

Return type:

str | TorrentsAddedMetadata

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

Add one or more peers to one or more torrents.

This method was introduced with qBittorrent v4.4.0 (Web API v2.3.0).

Raises:

InvalidRequest400Error – for invalid peers

Parameters:

peers (str | Iterable[str] | None) – one or more peers to add. each peer should take the form ‘host:port’
torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.

Return type:

TorrentsAddPeersDictionary

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

Add one or more tags to one or more torrents.

Note: Tags that do not exist will be created on-the-fly.

This method was introduced with qBittorrent v4.2.0 (Web API v2.3.0).

Parameters:

tags (str | Iterable[str] | None) – tag name or list of tags
torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.

Return type:

None

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

Add trackers to a torrent.

Raises:

NotFound404Error –

Parameters:

torrent_hash (str | None) – hash for torrent
urls (str | Iterable[str] | None) – tracker URLs to add to torrent

Return type:

None

torrents_add_webseeds(torrent_hash=None, urls=None, **kwargs) → None¶

Add webseeds to a torrent.

Raises:

NotFound404Error – torrent not found
InvalidRequest400Error – invalid URL

Parameters:

torrent_hash (str | None) – hash for torrent
urls (str | Iterable[str] | None) – list of webseed URLs to add to torrent

Return type:

None

torrents_bottom_priority(torrent_hashes=None, **kwargs) → None¶

Set torrent as lowest priority. Torrent Queuing must be enabled.

Raises:: Conflict409Error –
Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_categories(**kwargs) → TorrentCategoriesDictionary¶

Retrieve all category definitions.

This method was introduced with qBittorrent v4.1.4 (Web API v2.1.1).

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

Return type:: TorrentCategoriesDictionary

torrents_count() → int¶

Retrieve count of torrents.

Return type:: int

torrents_create_category(name=None, save_path=None, download_path=None, enable_download_path=None, **kwargs) → None¶

Create a new torrent category.

Raises:

Conflict409Error – if category name is not valid or unable to create

Parameters:

name (str | None) – name for new category
save_path (str | None) – location to save torrents for this category (added in Web API 2.1.0)
download_path (str | None) – download location for torrents with this category
enable_download_path (bool | None) – True or False to enable or disable download path

Return type:

None

torrents_create_tags(tags=None, **kwargs) → None¶

Create one or more tags.

This method was introduced with qBittorrent v4.2.0 (Web API v2.3.0).

Parameters:: tags (str | Iterable[str] | None) – tag name or list of tags
Return type:: None

torrents_decrease_priority(torrent_hashes=None, **kwargs) → None¶

Decrease the priority of a torrent. Torrent Queuing must be enabled.

Raises:: Conflict409Error –
Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

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

Remove a torrent from qBittorrent and optionally delete its files.

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
delete_files (bool | None) – True to delete the torrent’s files

Return type:

None

torrents_delete_tags(tags=None, **kwargs) → None¶

Delete one or more tags.

This method was introduced with qBittorrent v4.2.0 (Web API v2.3.0).

Parameters:: tags (str | Iterable[str] | None) – tag name or list of tags
Return type:: None

torrents_download_limit(torrent_hashes=None, **kwargs) → TorrentLimitsDictionary¶

Retrieve the download limit for one or more torrents.

Return type:: TorrentLimitsDictionary

torrents_edit_category(name=None, save_path=None, download_path=None, enable_download_path=None, **kwargs) → None¶

Edit an existing category.

This method was introduced with qBittorrent v4.1.3 (Web API v2.1.0).

Raises:

Conflict409Error – if category name is not valid or unable to create

Parameters:

name (str | None) – category to edit
save_path (str | None) – new location to save files for this category
download_path (str | None) – download location for torrents with this category
enable_download_path (bool | None) – True or False to enable or disable download path

Return type:

None

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

Replace a torrent’s tracker with a different one.

This method was introduced with qBittorrent v4.1.4 (Web API v2.2.0).

Raises:

Parameters:

torrent_hash (str | None) – hash for torrent
original_url (str | None) – URL for existing tracker
new_url (str | None) – new URL to replace
tier (str | int | None) – tracker’s tier (added in Web API v2.13.0)

Return type:

None

torrents_edit_webseed(torrent_hash=None, orig_url=None, new_url=None, **kwargs) → None¶

Edit a webseed for a torrent.

Raises:

NotFound404Error – torrent not found
Conflict409Error – orig_url is not a webseed for the torrent
InvalidRequest400Error – invalid URL

Parameters:

torrent_hash (str | None) – hash for torrent
orig_url (str | None) – webseed URL to be replaced
new_url (str | None) – webseed URL to replace with

Return type:

None

torrents_export(torrent_hash=None, **kwargs) → bytes¶

Export a .torrent file for the torrent.

This method was introduced with qBittorrent v4.5.0 (Web API v2.8.14).

Raises:

NotFound404Error – torrent not found
Conflict409Error – unable to export .torrent file

Parameters:

torrent_hash (str | None) – hash for torrent

Return type:

bytes

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

Set priority for one or more files.

Raises:

InvalidRequest400Error – if priority is invalid or at least one file ID is not an integer
NotFound404Error –
Conflict409Error – if torrent metadata has not finished downloading or at least one file was not found

Parameters:

torrent_hash (str | None) – hash for torrent
file_ids (str | int | Iterable[str | int] | None) – single file ID or a list.
priority (str | int | None) – priority for file(s) - https://github.com/qbittorrent/qBittorrent/wiki/WebUI-API-(qBittorrent-5.0)#user-content-set-file-priority

Return type:

None

torrents_files(torrent_hash=None, **kwargs) → TorrentFilesList¶

Retrieve individual torrent’s files.

Raises:: NotFound404Error –
Parameters:: torrent_hash (str | None) – hash for torrent
Return type:: TorrentFilesList

torrents_increase_priority(torrent_hashes=None, **kwargs) → None¶

Increase the priority of a torrent. Torrent Queuing must be enabled.

Raises:: Conflict409Error –
Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_info(status_filter=None, category=None, sort=None, reverse=None, limit=None, offset=None, torrent_hashes=None, tag=None, private=None, include_trackers=None, include_files=None, **kwargs) → TorrentInfoList¶

Retrieves list of info for torrents.

Parameters:

status_filter (Literal['all', 'downloading', 'seeding', 'completed', 'paused', 'stopped', 'active', 'inactive', 'resumed', 'running', 'stalled', 'stalled_uploading', 'stalled_downloading', 'checking', 'moving', 'errored'] | None) –
Filter list by torrent status:
- Original options: all, downloading, seeding, completed, paused, active, inactive, resumed, errored
- Added in Web API v2.4.1: stalled, stalled_uploading, and stalled_downloading
- Added in Web API v2.8.4: checking
- Added in Web API v2.8.18: moving
- Added in Web API v2.11.0: stopped (replaced paused), running (replaced resumed)
category (str | None) – Filter list by category
sort (str | None) – Sort list by any property returned
reverse (bool | None) – Reverse sorting
limit (str | int | None) – Limit length of list
offset (str | int | None) – Start of list (if < 0, offset from end of list)
torrent_hashes (str | Iterable[str] | None) – Filter list by hash (separate multiple hashes with a ‘|’) (added in Web API v2.0.1)
tag (str | None) – Filter list by tag (empty string means “untagged”; no “tag” parameter means “any tag”; added in Web API v2.8.3)
private (bool | None) – Filter list by private flag - use None to ignore; (added in Web API v2.11.1)
include_trackers (bool | None) – Include trackers in response; default False; (added in Web API v2.11.4)
include_files (bool | None) – Include files in response; default False; (added in Web API v2.11.7)

Return type:

TorrentInfoList

torrents_pause(torrent_hashes=None, **kwargs) → None¶

Stop one or more torrents in qBittorrent.

Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_piece_hashes(torrent_hash=None, **kwargs) → TorrentPieceInfoList¶

Retrieve individual torrent’s pieces’ hashes.

Raises:: NotFound404Error –
Parameters:: torrent_hash (str | None) – hash for torrent
Return type:: TorrentPieceInfoList

torrents_piece_states(torrent_hash=None, **kwargs) → TorrentPieceInfoList¶

Retrieve individual torrent’s pieces’ states.

Raises:: NotFound404Error –
Parameters:: torrent_hash (str | None) – hash for torrent
Return type:: TorrentPieceInfoList

torrents_properties(torrent_hash=None, **kwargs) → TorrentPropertiesDictionary¶

Retrieve individual torrent’s properties.

Raises:: NotFound404Error –
Parameters:: torrent_hash (str | None) – hash for torrent
Return type:: TorrentPropertiesDictionary

torrents_reannounce(torrent_hashes=None, **kwargs) → None¶

Reannounce a torrent.

This method was introduced with qBittorrent v4.1.2 (Web API v2.0.2).

Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_recheck(torrent_hashes=None, **kwargs) → None¶

Recheck a torrent in qBittorrent.

Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_remove_categories(categories=None, **kwargs) → None¶

Delete one or more categories.

Parameters:: categories (str | Iterable[str] | None) – categories to delete
Return type:: None

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

Add one or more tags to one or more torrents.

This method was introduced with qBittorrent v4.2.0 (Web API v2.3.0).

Parameters:

tags (str | Iterable[str] | None) – tag name or list of tags
torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.

Return type:

None

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

Remove trackers from a torrent.

This method was introduced with qBittorrent v4.1.4 (Web API v2.2.0).

Raises:

NotFound404Error –
Conflict409Error –

Parameters:

torrent_hash (str | None) – hash for torrent
urls (str | Iterable[str] | None) – tracker URLs to removed from torrent

Return type:

None

torrents_remove_webseeds(torrent_hash=None, urls=None, **kwargs) → None¶

Remove webseeds from a torrent.

Raises:

NotFound404Error –
InvalidRequest400Error – invalid URL

Parameters:

torrent_hash (str | None) – hash for torrent
urls (str | Iterable[str] | None) – list of webseed URLs to add to torrent

Return type:

None

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

Rename a torrent.

Raises:

NotFound404Error –

Parameters:

torrent_hash (str | None) – hash for torrent
new_torrent_name (str | None) – new name for torrent

Return type:

None

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

Rename a torrent file.

This method was introduced with qBittorrent v4.2.1 (Web API v2.4.0).

Raises:

Parameters:

torrent_hash (str | None) – hash for torrent
file_id (str | int | None) – id for file (removed in Web API v2.7)
new_file_name (str | None) – new name for file (removed in Web API v2.7)
old_path (str | None) – path of file to rename (added in Web API v2.7)
new_path (str | None) – new path of file to rename (added in Web API v2.7)

Return type:

None

torrents_rename_folder(torrent_hash=None, old_path=None, new_path=None, **kwargs) → None¶

Rename a torrent folder.

This method was introduced with qBittorrent v4.3.2 (Web API v2.7).

Raises:

Parameters:

torrent_hash (str | None) – hash for torrent
old_path (str | None) – path of file to rename (added in Web API v2.7)
new_path (str | None) – new path of file to rename (added in Web API v2.7)

Return type:

None

torrents_resume(torrent_hashes=None, **kwargs) → None¶

Start one or more torrents in qBittorrent.

Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

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

Enable or disable automatic torrent management for one or more torrents.

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
enable (bool | None) – Defaults to True if None or unset; use False to disable

Return type:

None

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

Set a category for one or more torrents.

Raises:

Conflict409Error – for bad category

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
category (str | None) – category to assign to torrent

Return type:

None

torrents_set_comment(comment=None, torrent_hashes=None, **kwargs) → None¶

Set a comment for one or more torrents.

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
comment (str | None) – comment to assign to torrent

Return type:

None

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

Set the download limit for one or more torrents.

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
limit (str | int | None) – bytes/second (-1 sets the limit to infinity)

Return type:

None

torrents_set_download_path(download_path=None, torrent_hashes=None, **kwargs) → None¶

Set the Download Path for one or more torrents.

This method was introduced with qBittorrent v4.4.0 (Web API v2.8.4).

Raises:

Forbidden403Error – cannot write to directory
Conflict409Error – cannot create directory

Parameters:

download_path (str | None) – file path to save torrent contents before torrent finishes downloading
torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.

Return type:

None

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

Force start one or more torrents.

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
enable (bool | None) – Defaults to True if None or unset; False is equivalent to torrents_resume().

Return type:

None

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

Set location for torrents’ files.

Raises:

Forbidden403Error – if the user doesn’t have permissions to write to the location (only before v4.5.2 - write check was removed.)
Conflict409Error – if the directory cannot be created at the location

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
location (str | None) – disk location to move torrent’s files

Return type:

None

torrents_set_save_path(save_path=None, torrent_hashes=None, **kwargs) → None¶

Set the Save Path for one or more torrents.

This method was introduced with qBittorrent v4.4.0 (Web API v2.8.4).

Raises:

Forbidden403Error – cannot write to directory
Conflict409Error – cannot create directory

Parameters:

save_path (str | None) – file path to save torrent contents
torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.

Return type:

None

torrents_set_share_limits(ratio_limit=None, seeding_time_limit=None, inactive_seeding_time_limit=None, share_limit_action=None, share_limits_mode=None, torrent_hashes=None, **kwargs) → None¶

Set share limits for one or more torrents.

This method was introduced with qBittorrent v4.1.1 (Web API v2.0.1).

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
ratio_limit (str | int | None) – max ratio to seed a torrent. (-2 means use the global value and -1 is no limit)
seeding_time_limit (str | int | None) – minutes (-2 means use the global value and -1 is no limit)
inactive_seeding_time_limit (str | int | None) – minutes (-2 means use the global value and -1 is no limit) (added in Web API v2.9.2)
share_limit_action (Literal['Default', 'Stop', 'Remove', 'RemoveWithContent', 'EnableSuperSeeding'] | None) – action once share limit is reached. Options: Default, Stop, Remove, RemoveWithContent, EnableSuperSeeding
share_limits_mode (Literal['Default', 'MatchAny', 'MatchAll'] | None) – mode once share limit is reached. Options: Default, MatchAny, MatchAll

Return type:

None

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

Set one or more torrents as super seeding.

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
enable (bool | None) – Defaults to True if None or unset; False to disable

Return type:

None

torrents_set_tags(tags=None, torrent_hashes=None, **kwargs) → None¶

Upsert one or more tags to one or more torrents.

Note: Tags that do not exist will be created on-the-fly.

This method was introduced with qBittorrent v5.1.0 (Web API v2.11.4).

Parameters:

tags (str | Iterable[str] | None) – tag name or list of tags
torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.

Return type:

None

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

Set the upload limit for one or more torrents.

Parameters:

torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
limit (str | int | None) – bytes/second (-1 sets the limit to infinity)

Return type:

None

torrents_start(torrent_hashes=None, **kwargs) → None¶

Start one or more torrents in qBittorrent.

Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_stop(torrent_hashes=None, **kwargs) → None¶

Stop one or more torrents in qBittorrent.

Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_tags(**kwargs) → TagList¶

Retrieve all tag definitions.

This method was introduced with qBittorrent v4.2.0 (Web API v2.3.0).

Return type:: TagList

torrents_toggle_first_last_piece_priority(torrent_hashes=None, **kwargs) → None¶

Toggle priority of first/last piece downloading.

Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_toggle_sequential_download(torrent_hashes=None, **kwargs) → None¶

Toggle sequential download for one or more torrents.

Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_top_priority(torrent_hashes=None, **kwargs) → None¶

Set torrent as highest priority. Torrent Queuing must be enabled.

Raises:: Conflict409Error –
Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: None

torrents_trackers(torrent_hash=None, **kwargs) → TrackersList¶

Retrieve individual torrent’s trackers. Tracker status is defined in TrackerStatus.

Raises:: NotFound404Error –
Parameters:: torrent_hash (str | None) – hash for torrent
Return type:: TrackersList

torrents_upload_limit(torrent_hashes=None, **kwargs) → TorrentLimitsDictionary¶

Retrieve the upload limit for one or more torrents.

Parameters:: torrent_hashes (str | Iterable[str] | None) – single torrent hash or list of torrent hashes. Or all for all torrents.
Return type:: TorrentLimitsDictionary

torrents_webseeds(torrent_hash=None, **kwargs) → WebSeedsList¶

Retrieve individual torrent’s web seeds.

Raises:: NotFound404Error – torrent not found
Parameters:: torrent_hash (str | None) – hash for torrent
Return type:: WebSeedsList

class Torrents(client) → None¶

Allows interaction with the Torrents API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host="localhost:8080", username="admin", password="adminadmin")
>>> # these 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.stop.all()
>>> client.torrents.start.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, tags=None, content_layout=None, ratio_limit=None, seeding_time_limit=None, download_path=None, use_download_path=None, stop_condition=None, add_to_top_of_queue=None, inactive_seeding_time_limit=None, share_limit_action=None, ssl_certificate=None, ssl_private_key=None, ssl_dh_params=None, is_stopped=None, **kwargs) → str | TorrentsAddedMetadata¶

Implements torrents_add().

Return type:: str | TorrentsAddedMetadata

add_trackers(torrent_hash=None, urls=None, **kwargs) → None¶

Implements torrents_add_trackers().

Return type:: None

add_webseeds(torrent_hash=None, urls=None, **kwargs) → None¶

Implements torrents_add_webseeds().

Return type:: None

count() → int¶

Implements torrents_count().

Return type:: int

edit_tracker(torrent_hash=None, original_url=None, new_url=None, tier=None, **kwargs) → None¶

Implements torrents_edit_tracker().

Return type:: None

edit_webseed(torrent_hash=None, orig_url=None, new_url=None, **kwargs) → None¶

Implements torrents_edit_webseed().

Return type:: None

export(torrent_hash=None, **kwargs) → bytes¶

Implements torrents_export().

Return type:: bytes

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

Implements torrents_file_priority().

Return type:: None

files(torrent_hash=None, **kwargs) → TorrentFilesList¶

Implements torrents_files().

Return type:: TorrentFilesList

piece_hashes(torrent_hash=None, **kwargs) → TorrentPieceInfoList¶

Implements torrents_piece_hashes().

Return type:: TorrentPieceInfoList

piece_states(torrent_hash=None, **kwargs) → TorrentPieceInfoList¶

Implements torrents_piece_states().

Return type:: TorrentPieceInfoList

properties(torrent_hash=None, **kwargs) → TorrentPropertiesDictionary¶

Implements torrents_properties().

Return type:: TorrentPropertiesDictionary

remove_trackers(torrent_hash=None, urls=None, **kwargs) → None¶

Implements torrents_remove_trackers().

Return type:: None

remove_webseeds(torrent_hash=None, urls=None, **kwargs) → None¶

Implements torrents_remove_webseeds().

Return type:: None

rename(torrent_hash=None, new_torrent_name=None, **kwargs) → None¶

Implements torrents_rename().

Return type:: None

rename_file(torrent_hash=None, file_id=None, new_file_name=None, old_path=None, new_path=None, **kwargs) → None¶

Implements torrents_rename_file().

Return type:: None

rename_folder(torrent_hash=None, old_path=None, new_path=None, **kwargs) → None¶

Implements torrents_rename_folder().

Return type:: None

trackers(torrent_hash=None, **kwargs) → TrackersList¶

Implements torrents_trackers().

Return type:: TrackersList

webseeds(torrent_hash=None, **kwargs) → WebSeedsList¶

Implements torrents_webseeds().

Return type:: WebSeedsList

class TorrentDictionary(data, client) → None¶

Bases: ClientCache[TorrentsAPIMixIn], ListEntry

Item in TorrentInfoList. Allows interaction with individual torrents via the Torrents API endpoints.

All torrent attributes are listed in https://github.com/qbittorrent/qBittorrent/blob/master/src/webui/api/serialize/serialize_torrent.h

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host="localhost:8080", username="admin", password="adminadmin")
>>> # these 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_id = torrent.hash # truncated v2 hash or v1 hash
>>> torrent_hash_v1 = torrent.infohash_v1
>>> torrent_hash_v2 = torrent.infohash_v2
>>> torrent_magnet = torrent.magnet_uri
>>> torrent_name = torrent.name
>>> # 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.start()
>>> torrent.stop()
>>> torrent.recheck()
>>> torrent.torrents_top_priority()
>>> torrent.setLocation(location="/home/user/torrents/")
>>> torrent.setCategory(category="video")

add_tags(tags=None, **kwargs) → None¶

Implements torrents_add_tags().

Return type:: None

add_trackers(urls=None, **kwargs) → None¶

Implements torrents_add_trackers().

Return type:: None

add_webseeds(urls, **kwargs) → None¶

Implements torrents_add_webseeds().

Return type:: None

bottom_priority(**kwargs) → None¶

Implements torrents_bottom_priority().

Return type:: None

decrease_priority(**kwargs) → None¶

Implements torrents_decrease_priority().

Return type:: None

delete(delete_files=None, **kwargs) → None¶

Implements torrents_delete().

Return type:: None

property download_limit: int¶: Implements torrents_download_limit().

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

Implements torrents_edit_tracker().

Return type:: None

edit_webseed(orig_url=None, new_url=None, **kwargs) → None¶

Implements torrents_edit_webseed().

Return type:: None

export(**kwargs) → bytes¶

Implements torrents_export().

Return type:: bytes

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

Implements torrents_file_priority().

Return type:: None

property files: TorrentFilesList¶: Implements torrents_files().

increase_priority(**kwargs) → None¶

Implements torrents_increase_priority().

Return type:: None

property info: TorrentDictionary¶: Returns data from torrents_info() for the torrent.

pause(**kwargs) → None¶

Implements torrents_stop().

Return type:: None

property piece_hashes: TorrentPieceInfoList¶: Implements torrents_piece_hashes().

property piece_states: TorrentPieceInfoList¶: Implements torrents_piece_states().

property properties: TorrentPropertiesDictionary¶: Implements torrents_properties().

reannounce(**kwargs) → None¶

Implements torrents_reannounce().

Return type:: None

recheck(**kwargs) → None¶

Implements torrents_recheck().

Return type:: None

remove_tags(tags=None, **kwargs) → None¶

Implements torrents_remove_tags().

Return type:: None

remove_trackers(urls=None, **kwargs) → None¶

Implements torrents_remove_trackers().

Return type:: None

remove_webseeds(urls=None, **kwargs) → None¶

Implements torrents_remove_webseeds().

Return type:: None

rename(new_name=None, **kwargs) → None¶

Implements torrents_rename().

Return type:: None

rename_file(file_id=None, new_file_name=None, old_path=None, new_path=None, **kwargs) → None¶

Implements torrents_rename_file().

Return type:: None

rename_folder(old_path=None, new_path=None, **kwargs) → None¶

Implements torrents_rename_folder().

Return type:: None

resume(**kwargs) → None¶

Implements torrents_start().

Return type:: None

setComment(comment=None, **kwargs) → None¶

Implements torrents_set_comment().

Return type:: None

set_auto_management(enable=None, **kwargs) → None¶

Implements torrents_set_auto_management().

Return type:: None

set_category(category=None, **kwargs) → None¶

Implements torrents_set_category().

Return type:: None

set_comment(comment=None, **kwargs) → None¶

Implements torrents_set_comment().

Return type:: None

set_download_limit(limit=None, **kwargs) → None¶

Implements torrents_set_download_limit().

Return type:: None

set_download_path(download_path=None, **kwargs) → None¶

Implements torrents_set_download_path().

Return type:: None

set_force_start(enable=None, **kwargs) → None¶

Implements torrents_set_force_start().

Return type:: None

set_location(location=None, **kwargs) → None¶

Implements torrents_set_location().

Return type:: None

set_save_path(save_path=None, **kwargs) → None¶

Implements torrents_set_save_path().

Return type:: None

set_share_limits(ratio_limit=None, seeding_time_limit=None, inactive_seeding_time_limit=None, share_limit_action=None, share_limits_mode=None, **kwargs) → None¶

Implements torrents_set_share_limits().

Return type:: None

set_super_seeding(enable=None, **kwargs) → None¶

Implements torrents_set_super_seeding().

Return type:: None

set_tags(tags=None, **kwargs) → None¶

Implements torrents_set_tags().

Return type:: None

set_upload_limit(limit=None, **kwargs) → None¶

Implements torrents_set_upload_limit().

Return type:: None

start(**kwargs) → None¶

Implements torrents_start().

Return type:: None

property state_enum: TorrentState¶: Torrent state enum.

stop(**kwargs) → None¶

Implements torrents_stop().

Return type:: None

sync_local() → None¶

Update local cache of torrent info.

Return type:: None

toggle_first_last_piece_priority(**kwargs) → None¶

Implements torrents_toggle_first_last_piece_priority().

Return type:: None

toggle_sequential_download(**kwargs) → None¶

Implements torrents_toggle_sequential_download().

Return type:: None

top_priority(**kwargs) → None¶

Implements torrents_top_priority().

Return type:: None

property trackers: TrackersList¶: Implements torrents_trackers().

property upload_limit: int¶: Implements torrents_upload_limit().

property webseeds: WebSeedsList¶: Implements torrents_webseeds().

class TorrentCategories(*args, client, **kwargs)¶

Bases: ClientCache[TorrentsAPIMixIn]

Allows interaction with torrent categories within the Torrents API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host="localhost:8080", username="admin", password="adminadmin")
>>> # these 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)
>>> categories = client.torrent_categories.categories
>>> # create or edit categories
>>> client.torrent_categories.create_category(name="Video", save_path="/home/user/torrents/Video")
>>> client.torrent_categories.edit_category(name="Video", save_path="/data/torrents/Video")
>>> # edit or create new by assignment
>>> client.torrent_categories.categories = dict(name="Video", save_path="/hone/user/")
>>> # delete categories
>>> client.torrent_categories.removeCategories(categories="Video")
>>> client.torrent_categories.removeCategories(categories=["Audio", "ISOs"])

property categories: TorrentCategoriesDictionary¶: Implements torrents_categories().

create_category(name=None, save_path=None, download_path=None, enable_download_path=None, **kwargs) → None¶

Implements torrents_create_category().

Return type:: None

edit_category(name=None, save_path=None, download_path=None, enable_download_path=None, **kwargs) → None¶

Implements torrents_edit_category().

Return type:: None

remove_categories(categories=None, **kwargs) → None¶

Implements torrents_remove_categories().

Return type:: None

class TorrentTags(*args, client, **kwargs)¶

Bases: ClientCache[TorrentsAPIMixIn]

Allows interaction with torrent tags within the “Torrent” API endpoints.

Usage:

>>> from qbittorrentapi import Client
>>> client = Client(host="localhost:8080", username="admin", password="adminadmin")
>>> tags = client.torrent_tags.tags
>>> client.torrent_tags.tags = "tv show"  # create category
>>> client.torrent_tags.create_tags(tags=["tv show", "linux distro"])
>>> client.torrent_tags.delete_tags(tags="tv show")