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, file_priorities=None, downloader=None, share_limits_mode=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)
file_priorities (Iterable[int] | None) – priority for each file in the torrent; must contain one entry per file and cannot be used when adding multiple torrents or when uploading torrent files (added in Web API v2.11.9)
downloader (str | None) – name of the search plugin to download the torrent with; only applies when adding by URL (added in Web API v2.13.1)
share_limits_mode (Literal['Default', 'MatchAny', 'MatchAll'] | None) – mode once share limit is reached. Options: Default, MatchAny, MatchAll (added in Web API v2.16.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(**kwargs) → 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_file(torrent_hash=None, file=None, **kwargs) → str¶

The file system path for a fully downloaded file within a torrent.

This method was introduced with qBittorrent v5.3.0 (Web API v2.16.0).

Raises:

NotFound404Error – torrent not found
Conflict409Error – torrent metadata unavailable, file not found, or file not fully downloaded

Parameters:

torrent_hash (str | None) – hash for torrent
file (str | int | None) – index of the file within the torrent or its path

Return type:

str

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_fetch_metadata(source=None, downloader=None, **kwargs) → TorrentMetadataDictionary¶

Retrieve the metadata for a torrent without adding it to qBittorrent.

This method was introduced with qBittorrent v5.2.0 (Web API v2.11.9).

Metadata is not necessarily available immediately. When qBittorrent must fetch it from peers or download it from a URL, the response is empty and qBittorrent continues retrieving it in the background; call this method again with the same source to collect the result.

Raises:

InvalidRequest400Error – if source cannot be parsed or downloader is not a valid search plugin

Parameters:

source (str | None) – URL (http://, https://, magnet:) or info hash
downloader (str | None) – name of the search plugin to download the torrent with

Return type:

TorrentMetadataDictionary

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_parse_metadata(torrent_files=None, **kwargs) → TorrentMetadataList¶

Parse the metadata of one or more torrent files without adding them.

This method was introduced with qBittorrent v5.2.0 (Web API v2.11.9).

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:

Return type:

TorrentMetadataList

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_availability(torrent_hash=None, **kwargs) → TorrentPieceInfoList¶

Retrieve the number of copies of each piece available across all peers.

This method was introduced with qBittorrent v5.2.0 (Web API v2.15.1).

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

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, urls=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.
urls (str | Iterable[str] | None) – single tracker URL or list of tracker URLs to reannounce to; defaults to all trackers for the torrent(s) (added in Web API v2.11.10)

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_save_metadata(source=None, **kwargs) → bytes¶

Export a .torrent file from previously fetched metadata.

This method was introduced with qBittorrent v5.2.0 (Web API v2.11.9).

The metadata must already have been retrieved with torrents_fetch_metadata() or torrents_parse_metadata().

Raises:

NotFound404Error – if source is unknown
Conflict409Error – if metadata is not yet available

Parameters:

source (str | None) – URL (http://, https://, magnet:) or info hash

Return type:

bytes

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 | float | 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 (added in Web API v2.10.4)
share_limits_mode (Literal['Default', 'MatchAny', 'MatchAll'] | None) – mode once share limit is reached. Options: Default, MatchAny, MatchAll (added in Web API v2.16.0)

Return type:

None

torrents_set_ssl_parameters(torrent_hash=None, ssl_certificate=None, ssl_private_key=None, ssl_dh_params=None, **kwargs) → None¶

Set the SSL parameters for an SSL torrent.

This method was introduced with qBittorrent v5.0.0 (Web API v2.10.3).

Raises:

NotFound404Error –
InvalidRequest400Error – if the SSL parameters are not valid

Parameters:

torrent_hash (str | None) – hash for torrent
ssl_certificate (str | None) – peer certificate (in PEM format)
ssl_private_key (str | None) – peer private key
ssl_dh_params (str | None) – Diffie-Hellman parameters

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_ssl_parameters(torrent_hash=None, **kwargs) → TorrentSSLParametersDictionary¶

Retrieve the SSL parameters for an SSL torrent.

This method was introduced with qBittorrent v5.0.0 (Web API v2.10.3).

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

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, forced=None, file_priorities=None, downloader=None, share_limits_mode=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(**kwargs) → int¶

Implements torrents_count().

Return type:: int

download_file(torrent_hash=None, file=None, **kwargs) → str¶

Implements torrents_download_file().

Return type:: str

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

fetch_metadata(source=None, downloader=None, **kwargs) → TorrentMetadataDictionary¶

Implements torrents_fetch_metadata().

Return type:: TorrentMetadataDictionary

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

parse_metadata(torrent_files=None, **kwargs) → TorrentMetadataList¶

Implements torrents_parse_metadata().

Return type:: TorrentMetadataList

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

Implements torrents_piece_availability().

Return type:: TorrentPieceInfoList

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

save_metadata(source=None, **kwargs) → bytes¶

Implements torrents_save_metadata().

Return type:: bytes

set_ssl_parameters(torrent_hash=None, ssl_certificate=None, ssl_private_key=None, ssl_dh_params=None, **kwargs) → None¶

Implements torrents_set_ssl_parameters().

Return type:: None

ssl_parameters(torrent_hash=None, **kwargs) → TorrentSSLParametersDictionary¶

Implements torrents_ssl_parameters().

Return type:: TorrentSSLParametersDictionary

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

download_file(file=None, **kwargs) → str¶

Implements torrents_download_file().

Return type:: str

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_availability: TorrentPieceInfoList¶: Implements torrents_piece_availability().

property piece_hashes: TorrentPieceInfoList¶: Implements torrents_piece_hashes().

property piece_states: TorrentPieceInfoList¶: Implements torrents_piece_states().

property properties: TorrentPropertiesDictionary¶: Implements torrents_properties().

reannounce(urls=None, **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_ssl_parameters(ssl_certificate=None, ssl_private_key=None, ssl_dh_params=None, **kwargs) → None¶

Implements torrents_set_ssl_parameters().

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

property ssl_parameters: TorrentSSLParametersDictionary¶: Implements torrents_ssl_parameters().

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