Download Clients#

Download clients retrieve media files being tracked by Sonarr, and store them in a location Sonarr can access to manage the downloaded files.

Download clients that use Usenet or BitTorrent can be configured, as well as remote path mappings and other related options.

---

sonarr:
  settings:
    download_clients:
      enable_completed_download_handling: true
      redownload_failed: true
      delete_unmanaged: true
      definitions:
        Transmission:
          type: "transmission"
          host: "transmission"
          port: 9091
        ...
      remote_path_mappings:
        definitions:
          - host: "transmission"
            remote_path: "/remote/path"
            local_path: "/local/path"
          ...
enable_completed_download_handling: bool = True class-attribute instance-attribute #

Automatically import completed downloads from download clients.

redownload_failed: bool = True class-attribute instance-attribute #

Automatically search for and attempt to download a different release.

delete_unmanaged: bool = False class-attribute instance-attribute #

Automatically delete download clients not defined in Buildarr.

definitions: Dict[str, Annotated[DownloadClientType, Field(discriminator='type')]] = {} class-attribute instance-attribute #

Download client definitions, for connecting with external media downloaders.

remote_path_mappings = SonarrRemotePathMappingsSettingsConfig() class-attribute instance-attribute #

Configuration for mapping paths on download client hosts to their counterparts on this Sonarr instance.

For more information, refer to "Configuring remote path mappings".

Note

Before Sonarr can send requests to download clients, at least one Usenet or torrent indexer will need to be configured. Sonarr will then send download requests to a compatible client, or the download client the indexer has been assigned to.

Configuring download clients#

Download clients are defined using the following format. Here is an example of a Transmission download client being configured.

---

sonarr:
  settings:
    download_clients:
      definitions:
        Transmission: # Name of the download client
          type: "transmission" # Type of download client
          enable: true # Enable the download client in Sonarr
          host: "transmission"
          port: 9091
          category: "sonarr"
          # Define any other type-specific or global
          # download client attributes as needed.

Every download client definition must have the correct type value defined, to tell Buildarr what type of download client to configure. The name of the download client definition is just a name, and has no meaning.

enable can be set to False to keep the download client configured on Sonarr, but disabled so that it is inactive.

The below attributes can be defined on any type of download client.

enable: bool = True class-attribute instance-attribute #

When True, this download client is active and Sonarr is able to send requests to it.

priority: int = 1 class-attribute instance-attribute #

Download client priority.

Clients with a lower value are prioritised. Round-robin is used for clients with the same priority.

remove_completed_downloads: bool = True class-attribute instance-attribute #

Remove completed downloads from the download client history.

For torrents, this happens once seeding is complete.

remove_failed_downloads: bool = True class-attribute instance-attribute #

Remove failed downloads from the download client history. (Usenet clients only)

tags: Set[NonEmptyStr] = set() class-attribute instance-attribute #

Sonarr tags to assign to the download clients. Only media under those tags will be assigned to this client.

If no tags are assigned, all media can use the client.

Usenet download clients#

These download clients retrieve media using the popular Usenet discussion and content delivery system.

Download Station#

Download client which uses Usenet via Download Station.

type: Literal['downloadstation-usenet'] = 'downloadstation-usenet' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

Download Station host name.

port: Port = 5000 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

username: NonEmptyStr instance-attribute #

User name to use when authenticating with the download client.

password: Password instance-attribute #

Password to use to authenticate the download client user.

category: Optional[str] = None class-attribute instance-attribute #

Associate media from Sonarr with a category. Creates a [category] subdirectory in the output directory.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

directory: Optional[str] = None class-attribute instance-attribute #

Optional shared folder to put downloads into.

Leave blank, set to null or undefined to use the default download client location.

NZBGet#

NZBGet download client.

type: Literal['nzbget'] = 'nzbget' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

NZBGet host name.

port: Port = 5000 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: Optional[str] = None class-attribute instance-attribute #

Adds a prefix to the NZBGet url, e.g. http://[host]:[port]/[url_base]/jsonrpc.

username: NonEmptyStr instance-attribute #

User name to use when authenticating with the download client.

password: Password instance-attribute #

Password to use to authenticate the download client user.

category: Optional[str] = None class-attribute instance-attribute #

Associate media from Sonarr with a category.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

recent_priority: NzbgetPriority = NzbgetPriority.normal class-attribute instance-attribute #

Priority to use when grabbing episodes that aired within the last 14 days.

Values:

  • verylow
  • low
  • normal
  • high
  • veryhigh
  • force
older_priority: NzbgetPriority = NzbgetPriority.normal class-attribute instance-attribute #

Priority to use when grabbing episodes that aired over 14 days ago.

Values:

  • verylow
  • low
  • normal
  • high
  • veryhigh
  • force
add_paused: bool = False class-attribute instance-attribute #

Add media to the download client in the paused state.

This option requires NZBGet version 16.0 or later.

NZBVortex#

NZBVortex download client.

type: Literal['nzbvortex'] = 'nzbvortex' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

NZBVortex host name.

port: Port = 4321 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: Optional[str] = None class-attribute instance-attribute #

Adds a prefix to the NZBVortex url, e.g. http://[host]:[port]/[url_base]/api.

api_key: Password instance-attribute #

API key to use to authenticate with the download client.

category: Optional[str] = None class-attribute instance-attribute #

Associate media from Sonarr with a category.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

recent_priority: NzbvortexPriority = NzbvortexPriority.normal class-attribute instance-attribute #

Priority to use when grabbing episodes that aired within the last 14 days.

Values:

  • low
  • normal
  • high
older_priority: NzbvortexPriority = NzbvortexPriority.normal class-attribute instance-attribute #

Priority to use when grabbing episodes that aired over 14 days ago.

Values:

  • low
  • normal
  • high

Pneumatic#

Download client for the Pneumatic NZB add-on for Kodi/XMBC.

type: Literal['pneumatic'] = 'pneumatic' class-attribute instance-attribute #

Type value associated with this kind of download client.

nzb_folder: NonEmptyStr instance-attribute #

Folder in which Sonarr will store .nzb files.

This folder will need to be reachable from Kodi/XMBC.

strm_folder: NonEmptyStr instance-attribute #

Folder from which .strm files will be imported by Drone.

SABnzbd#

SABnzbd download client.

type: Literal['sabnzbd'] = 'sabnzbd' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

SABnzbd host name.

port: Port = 4321 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: Optional[str] = None class-attribute instance-attribute #

Adds a prefix to the SABnzbd URL, e.g. http://[host]:[port]/[url_base]/api/.

api_key: Password instance-attribute #

API key to use to authenticate with the download client.

category: Optional[str] = None class-attribute instance-attribute #

Associate media from Sonarr with a category.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

recent_priority: SabnzbdPriority = SabnzbdPriority.default class-attribute instance-attribute #

Priority to use when grabbing episodes that aired within the last 14 days.

Values:

  • default
  • paused
  • low
  • normal
  • high
  • force
older_priority: SabnzbdPriority = SabnzbdPriority.default class-attribute instance-attribute #

Priority to use when grabbing episodes that aired over 14 days ago.

Values:

  • default
  • paused
  • low
  • normal
  • high
  • force

Usenet Blackhole#

Usenet Blackhole download client.

type: Literal['usenet-blackhole'] = 'usenet-blackhole' class-attribute instance-attribute #

Type value associated with this kind of download client.

nzb_folder: NonEmptyStr instance-attribute #

Folder in which Sonarr will store .nzb files.

watch_folder: NonEmptyStr instance-attribute #

Folder from which Sonarr should import completed downloads.

Torrent download clients#

These download clients use the BitTorrent peer-to-peer file sharing protocol to retrieve media files.

Aria2#

Aria2 download client.

type: Literal['aria2'] = 'aria2' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

Aria2 host name.

port: Port = 6800 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

rpc_path: NonEmptyStr = '/rpc' class-attribute instance-attribute #

XML RPC path in the Aria2 client URL.

secret_token: Password instance-attribute #

Secret token to use to authenticate with the download client.

Deluge#

Deluge download client.

type: Literal['deluge'] = 'deluge' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

Deluge host name.

port: Port = 8112 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: Optional[str] = None class-attribute instance-attribute #

Adds a prefix to the Deluge JSON URL, e.g. http://[host]:[port]/[url_base]/json.

password: Password instance-attribute #

Password to use to authenticate the download client user.

category: Optional[str] = 'tv-sonarr' class-attribute instance-attribute #

Associate media from Sonarr with a category.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

postimport_category: Optional[str] = None class-attribute instance-attribute #

Category for Sonarr to set after it has imported the download.

Sonarr will not remove torrents in that category even if seeding has finished. Leave blank, set to null or undefined to keep the same category.

recent_priority: DelugePriority = DelugePriority.last class-attribute instance-attribute #

Priority to use when grabbing episodes that aired within the last 14 days.

Values:

  • last
  • first
older_priority: DelugePriority = DelugePriority.last class-attribute instance-attribute #

Priority to use when grabbing episodes that aired over 14 days ago.

Values:

  • last
  • first

Download Station#

Download client which uses torrents via Download Station.

type: Literal['downloadstation-torrent'] = 'downloadstation-torrent' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

Download Station host name.

port: Port = 5000 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

username: NonEmptyStr instance-attribute #

User name to use when authenticating with the download client.

password: Password instance-attribute #

Password to use to authenticate the download client user.

category: Optional[str] = None class-attribute instance-attribute #

Associate media from Sonarr with a category. Creates a [category] subdirectory in the output directory.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

directory: Optional[str] = None class-attribute instance-attribute #

Optional shared folder to put downloads into.

Leave blank, set to null or undefined to use the default download client location.

Flood#

Flood download client.

type: Literal['flood'] = 'flood' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

Flood host name.

port: Port = 3000 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: Optional[str] = None class-attribute instance-attribute #

Optionally adds a prefix to Flood API, such as [protocol]://[host]:[port]/[url_base]api.

username: NonEmptyStr instance-attribute #

User name to use when authenticating with the download client.

password: Password instance-attribute #

Password to use to authenticate the download client user.

destination: Optional[str] = None class-attribute instance-attribute #

Manually specified download destination.

flood_tags: Set[NonEmptyStr] = {'sonarr'} class-attribute instance-attribute #

Initial tags of a download within Flood.

To be recognized, a download must have all initial tags. This avoids conflicts with unrelated downloads.

postimport_tags: Set[NonEmptyStr] = set() class-attribute instance-attribute #

Tags to append within Flood after a download has been imported into Sonarr.

additional_tags: Set[FloodMediaTag] = set() class-attribute instance-attribute #

Adds properties of media as tags within Flood.

start_on_add: bool = True class-attribute instance-attribute #

Immediately start download once the media has been added to the client.

Hadouken#

Hadouken download client.

type: Literal['hadouken'] = 'hadouken' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

Hadouken host name.

port: Port = 7070 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: Optional[str] = None class-attribute instance-attribute #

Adds a prefix to the Hadouken url, e.g. http://[host]:[port]/[url_base]/api.

username: NonEmptyStr instance-attribute #

User name to use when authenticating with the download client.

password: Password instance-attribute #

Password to use to authenticate the download client user.

category: NonEmptyStr = 'sonarr-tv' class-attribute instance-attribute #

Associate media from Sonarr with a category.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

qBittorrent#

qBittorrent download client.

type: Literal['qbittorrent'] = 'qbittorrent' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

qBittorrent host name.

port: Port = 8080 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: Optional[str] = None class-attribute instance-attribute #

Adds a prefix to the qBittorrent URL, e.g. http://[host]:[port]/[url_base]/api.

username: Optional[str] = None class-attribute instance-attribute #

User name to use when authenticating with the download client, if required.

password: Optional[SecretStr] = None class-attribute instance-attribute #

Password to use to authenticate the download client user, if required.

category: Optional[str] = 'tv-sonarr' class-attribute instance-attribute #

Associate media from Sonarr with a category.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

postimport_category: Optional[str] = None class-attribute instance-attribute #

Category for Sonarr to set after it has imported the download.

Sonarr will not remove torrents in that category even if seeding has finished. Leave blank, set to null or undefined to keep the same category.

recent_priority: QbittorrentPriority = QbittorrentPriority.last class-attribute instance-attribute #

Priority to use when grabbing episodes that aired within the last 14 days.

Values:

  • last
  • first
older_priority: QbittorrentPriority = QbittorrentPriority.last class-attribute instance-attribute #

Priority to use when grabbing episodes that aired over 14 days ago.

Values:

  • last
  • first
initial_state: QbittorrentState = QbittorrentState.start class-attribute instance-attribute #

Initial state for torrents added to qBittorrent.

Note that forced torrents do not abide by seed restrictions.

sequential_order: bool = False class-attribute instance-attribute #

Download files in sequential order.

This option requires qBittorrent version 4.1.0 or later.

first_and_last_first: bool = False class-attribute instance-attribute #

Download first and last pieces of a file first.

This option requires qBittorrent version 4.1.0 or later.

RTorrent (ruTorrent)#

RTorrent (ruTorrent) download client.

type: Literal['rtorrent', 'rutorrent'] = 'rtorrent' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

RTorrent host name.

port: Port = 8080 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: NonEmptyStr = 'RPC2' class-attribute instance-attribute #

Path to the XMLRPC endpoint, e.g. http(s)://[host]:[port]/[url_base].

When using RTorrent this usually is RPC2 or plugins/rpc/rpc.php.

username: NonEmptyStr instance-attribute #

User name to use when authenticating with the download client.

password: Password instance-attribute #

Password to use to authenticate the download client user.

category: Optional[str] = 'tv-sonarr' class-attribute instance-attribute #

Associate media from Sonarr with a category.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

postimport_category: Optional[str] = None class-attribute instance-attribute #

Category for Sonarr to set after it has imported the download.

Sonarr will not remove torrents in that category even if seeding has finished. Leave blank, set to null or undefined to keep the same category.

recent_priority: RtorrentPriority = RtorrentPriority.normal class-attribute instance-attribute #

Priority to use when grabbing episodes that aired within the last 14 days.

Values:

  • verylow
  • low
  • normal
  • high
older_priority: RtorrentPriority = RtorrentPriority.normal class-attribute instance-attribute #

Priority to use when grabbing episodes that aired over 14 days ago.

Values:

  • verylow
  • low
  • normal
  • high
add_stopped: bool = False class-attribute instance-attribute #

Enabling will add torrents and magnets to RTorrent in a stopped state.

This may break magnet files.

Torrent Blackhole#

Torrent Blackhole download client.

type: Literal['torrent-blackhole'] = 'torrent-blackhole' class-attribute instance-attribute #

Type value associated with this kind of download client.

torrent_folder: NonEmptyStr instance-attribute #

Folder in which Sonarr will store .torrent files.

watch_folder: NonEmptyStr instance-attribute #

Folder from which Sonarr should import completed downloads.

save_magnet_files: bool = False class-attribute instance-attribute #

Save the magnet link if no .torrent file is available.

Only useful if the download client supports magnets saved to a file.

magnet_file_extension: NonEmptyStr = '.magnet' class-attribute instance-attribute #

Extension to use for magnet links.

read_only: bool = True class-attribute instance-attribute #

Instead of moving files, this will instruct Sonarr to copy or hard link (depending on settings/system configuration).

Transmission/Vuze#

Transmission and Vuze use the same configuration parameters.

To use Transmission, set the type attribute in the download client to transmission.

To use Vuze, set the type attribute in the download client to vuze.

Configuration options common to both Transmission and Vuze download clients:

host: NonEmptyStr instance-attribute #

Transmission/Vuze host name.

port: Port = 9091 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: NonEmptyStr = '/transmission/' class-attribute instance-attribute #

Adds a prefix to the Transmission/Vuze RPC url, e.g.http://[host]:[port][url_base]rpc.

This is set by default in most clients to /transmission/.

username: Optional[str] = None class-attribute instance-attribute #

User name to use when authenticating with the download client, if required.

password: Optional[Password] = None class-attribute instance-attribute #

Password to use to authenticate the download client user, if required.

category: Optional[str] = None class-attribute instance-attribute #

Associate media from Sonarr with a category. Creates a [category] subdirectory in the output directory.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

category and directory are mutually exclusive, only one of them can be set at a time.

directory: Optional[str] = None class-attribute instance-attribute #

Optional shared folder to put downloads into.

Leave blank, set to null or undefined to use the default download client location.

category and directory are mutually exclusive, only one of them can be set at a time.

recent_priority: TransmissionPriority = TransmissionPriority.last class-attribute instance-attribute #

Priority to use when grabbing episodes that aired within the last 14 days.

Values:

  • last
  • first
older_priority: TransmissionPriority = TransmissionPriority.last class-attribute instance-attribute #

Priority to use when grabbing episodes that aired over 14 days ago.

Values:

  • last
  • first
add_paused: bool = False class-attribute instance-attribute #

Add media to the download client in the Paused state.

uTorrent#

uTorrent download client.

type: Literal['utorrent'] = 'utorrent' class-attribute instance-attribute #

Type value associated with this kind of download client.

host: NonEmptyStr instance-attribute #

uTorrent host name.

port: Port = 8080 class-attribute instance-attribute #

Download client access port.

use_ssl: bool = False class-attribute instance-attribute #

Use a secure connection when connecting to the download client.

url_base: Optional[str] = None class-attribute instance-attribute #

Adds a prefix to the uTorrent URL, e.g. http://[host]:[port]/[url_base]/api.

username: NonEmptyStr instance-attribute #

User name to use when authenticating with the download client.

password: Password instance-attribute #

Password to use to authenticate the download client user.

category: Optional[str] = 'tv-sonarr' class-attribute instance-attribute #

Associate media from Sonarr with a category.

Adding a category specific to Sonarr avoids conflicts with unrelated non-Sonarr downloads. Using a category is optional, but strongly recommended.

postimport_category: Optional[str] = None class-attribute instance-attribute #

Category for Sonarr to set after it has imported the download.

Sonarr will not remove torrents in that category even if seeding has finished. Leave blank, set to null or undefined to keep the same category.

recent_priority: UtorrentPriority = UtorrentPriority.last class-attribute instance-attribute #

Priority to use when grabbing episodes that aired within the last 14 days.

Values:

  • last
  • first
older_priority: UtorrentPriority = UtorrentPriority.last class-attribute instance-attribute #

Priority to use when grabbing episodes that aired over 14 days ago.

Values:

  • last
  • first
initial_state: UtorrentState = UtorrentState.start class-attribute instance-attribute #

Initial state for torrents added to uTorrent.

Configuring remote path mappings#

Remote path mappings are used to associate a path on a download client remote host with its associated path on the local Sonarr instance.

The main use case for this is when Sonarr and the download client are not running on the same system, or when Docker is used to isolate these services and the mountpoints for media locations are not consistent between the containers.

sonarr:
  settings:
    download_clients:
      definitions:
        Transmission:
          type: "transmission"
          host: "transmission"
          port: 9091
      remote_path_mappings:
        delete_unmanaged: false # Optional
        definitions:
          - host: "transmission"
            remote_path: "/remote/path"
            local_path: "/local/path"
            ensure: "present" # Optional

Remote path mappings can be difficult to properly configure. TRaSH-Guides provides an excellent guide that explains what they are for, and how to use them.

delete_unmanaged: bool = False class-attribute instance-attribute #

Automatically delete remote path mappings not configured in Buildarr.

Deleting existing remote path mappings can cause problems with a running Sonarr instance. Think carefully before you enable this option.

definitions: List[RemotePathMapping] = [] class-attribute instance-attribute #

Remote path mapping definitions.

Remote path mapping parameters#

Remote path mapping definitions themselves are relatively simple.

They can be configured with a desired ensure state, however, which Buildarr uses to control whether to create or delete the remote path mapping. Ensure this value is set appropriately.

host: NonEmptyStr instance-attribute #

The name of the host, as specified for the remote download client.

remote_path: OSAgnosticPath instance-attribute #

Root path to the directory that the download client accesses.

Changed in version 0.6.4: Path checking will now match paths whether or not the defined path ends in a trailing slash. Path checking on Windows paths is now case-insensitive.

local_path: OSAgnosticPath instance-attribute #

The path that Sonarr should use to access the remote path locally.

Changed in version 0.6.4: Path checking will now match paths whether or not the defined path ends in a trailing slash. Path checking on Windows paths is now case-insensitive.

ensure: Ensure = Ensure.present class-attribute instance-attribute #

Desired state for this resource.

If set to present, the resource is created on the remote instance if it does not exist.

If set to absent, the resource will be destroyed on the remote instance if it exists. This takes effect even if the delete_unmanaged is set to False for all remote path mappings.