Import Lists#

Using import lists, Sonarr can monitor and import episodes from external sources.

sonarr:
  settings:
    import_lists:
      delete_unmanaged: False # Default is `false`
      delete_unmanaged_exclusions: true # Default is `false`
      definitions:
        Plex: # Name of import list definition
          type: "plex-watchlist" # Type of import list to use
          # Attributes common to all watch list types
          enable_automatic_add: true
          monitor: "all-episodes"
          series_type: "standard"
          season_folder: true
          tags:
            - "example"
          # Plex-specific attributes
          access_token: "..."
        # Add more import lists here.
      exclusions:
        72662: "Teletubbies" # TVDB ID is key, set an artibrary title as value

Media can be queued on the source, and Sonarr will automatically import them, look for suitable releases, and download them.

Media that you don't want to import can be ignored using the exclusions attribute.

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

Automatically delete import lists not defined in Buildarr.

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

Automatically delete import list excusions not defined in Buildarr.

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

Import list definitions go here.

exclusions: Dict[PositiveInt, NonEmptyStr] = {} class-attribute instance-attribute #

Dictionary of TV series that should be excluded from being imported.

The key is the TVDB ID of the series to exclude, the value is a title to give the series in the Sonarr UI.

Configuring import lists#

The following

For more information on how an import list should be setup, refer to this guide on WikiArr.

All import list types can have the following attributes configured.

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

Automatically add series to Sonarr upon syncing.

monitor: Monitor = Monitor.all_episodes class-attribute instance-attribute #

Define how Sonarr should monitor existing and new episodes of series.

Values:

  • all-episodes - Monitor all episodes except specials
  • future-episodes - Monitor episodes that have not aired yet
  • missing-episodes - Monitor episodes that do not have files or have not aired yet
  • existing-episodes - Monitor episodes that have files or have not aired yet
  • pilot-episode - Monitor only the pilot episode of a series
  • first-season - Monitor all episodes of the first season (all other seasons will be ignored)
  • only-latest-season - Monitor all episodes of the latest season and future seasons
  • none - No episodes will be monitored
root_folder: NonEmptyStr instance-attribute #

The root folder to add list items to.

This attribute is required.

quality_profile: NonEmptyStr instance-attribute #

The name of the quality profile list items will be added with.

This attribute is required.

language_profile: NonEmptyStr instance-attribute #

The name of the language profile list items will be added with.

This attribute is required.

series_type: SeriesType = SeriesType.standard class-attribute instance-attribute #

The type of series that get imported from this import list. This option affects how Sonarr handles the media, such as renaming.

Values:

  • standard - Episodes released with an SxxEyy pattern
  • daily - Episodes released daily or less frequently that use year-month-day (2017-05-25)
  • anime - Episodes released using an absolute episode number
season_folder: bool = True class-attribute instance-attribute #

Use a season folder for series imported from this import list.

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

Tags to assign to items imported from this import list.

Sonarr#

Import items from another Sonarr instance.

The linked Sonarr instance must be the same major version as this defined Sonarr instance. For example, a Sonarr V3 instance cannot connect with a Sonarr V4 instance, and vice versa.

...
  import_lists:
    definitions:
      Sonarr:
        type: "sonarr"
        # Global import list options.
        root_folder: "/path/to/videos"
        quality_profile: "HD/SD"
        language_profile: "English"
        # Sonarr import list-specific options.
        full_url: "http://sonarr:8989"
        api_key: "1a2b3c4d5e1a2b3c4d5e1a2b3c4d5e1a"
        source_quality_profiles:
          - 11
          ...
        source_language_profiles:
          - 22
          ...
        source_tags:
          - 33
          ...

This import list supports instance references to another Buildarr-defined Sonarr instance using instance_name.

In this mode, you can specify instance_name in place of api_key, and use actual names for the source language profiles, quality profiles and tags, instead of IDs which are subject to change.

Here is an example of one Sonarr instance (sonarr-4k) referencing another instance (sonarr-hd), using it as an import list.

sonarr:
  instances:
    sonarr-hd:
      hostname: "localhost"
      port: 8989
    sonarr-4k:
      hostname: "localhost"
      port: 8990
      settings:
        import_lists:
          definitions:
            Sonarr (HD):
              type: "sonarr"
              # Global import list options.
              root_folder: "/path/to/videos"
              quality_profile: "4K"
              language_profile: "English"
              # Sonarr import list-specific options.
              full_url: "http://sonarr:8989"
              instance_name: "sonarr-hd"
              source_quality_profiles:
                - "HD/SD"
              source_language_profiles:
                - "English"
              source_tags:
                - "shows"

An important thing to keep in mind is that unless Buildarr is on the same network as the rest of the *Arr stack, the hostnames and ports may differ to what the Sonarr instances will use to communicate with each other. full_url should be set to what the Sonarr instance itself will use to link to the target instance.

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

Type value associated with this kind of import list.

instance_name: Optional[InstanceName] = Field(None, plugin='sonarr') class-attribute instance-attribute #

The name of the Sonarr instance within Buildarr, if linking this Sonarr instance with another Buildarr-defined Sonarr instance.

New in version 0.3.0.

full_url: AnyHttpUrl instance-attribute #

The URL that this Sonarr instance will use to connect to the source Sonarr instance.

api_key: Optional[SonarrApiKey] = None class-attribute instance-attribute #

API key used to access the source Sonarr instance.

If a Sonarr instance managed by Buildarr is not referenced using instance_name, this attribute is required.

source_quality_profiles: Set[Union[PositiveInt, NonEmptyStr]] = Field(set(), alias='source_quality_profile_ids') class-attribute instance-attribute #

List of IDs (or names) of the quality profiles on the source instance to import from.

Quality profile names can only be used if instance_name is used to link to a Buildarr-defined Sonarr instance. If linking to a Sonarr instance outside Buildarr, IDs must be used.

Changed in version 0.3.0: Renamed from source_quality_profile_ids (which is still valid as an alias), and added support for quality profile names.

source_language_profiles: Set[Union[PositiveInt, NonEmptyStr]] = Field(set(), alias='source_language_profile_ids') class-attribute instance-attribute #

List of IDs (or names) of the language profiles on the source instance to import from.

Language profile names can only be used if instance_name is used to link to a Buildarr-defined Sonarr instance. If linking to a Sonarr instance outside Buildarr, IDs must be used.

Changed in version 0.3.0: Renamed from source_language_profile_ids (which is still valid as an alias), and added support for language profile names.

source_tags: Set[Union[PositiveInt, NonEmptyStr]] = Field(set(), alias='source_tag_ids') class-attribute instance-attribute #

List of IDs (or names) of the tags on the source instance to import from.

Tag names can only be used if instance_name is used to link to a Buildarr-defined Sonarr instance. If linking to a Sonarr instance outside Buildarr, IDs must be used.

Changed in version 0.3.0: Renamed from source_tag_ids (which is still valid as an alias), and added support for tag names.

Plex#

Import items from a Plex watchlist.

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

Type value associated with this kind of import list.

access_token: Password instance-attribute #

Plex authentication token.

If unsure on where to find this token, follow this guide from Plex.tv.

Trakt#

Import added media from a list on the Trakt media tracker.

Note

Sonarr directly authenticates with Trakt to generate tokens for it to use. At the moment, the easiest way to generate the tokens for Buildarr is to do it using the GUI within Sonarr, and use the following shell command to retrieve the generated configuration.

$ curl -X "GET" "<sonarr-url>/api/v3/notification" -H "X-Api-Key: <api-key>"

The following parameters are common to all Trakt import list types. The authenticated-related parameters (access_token, refresh_token, expires, auth_user) are required.

access_token: Password instance-attribute #

Access token for Sonarr from Trakt.

refresh_token: Password instance-attribute #

Refresh token for Sonarr from Trakt.

expires: datetime instance-attribute #

Expiry date-time of the access token, preferably in ISO-8601 format and in UTC.

Example: 2023-05-10T15:34:08.117451Z

auth_user: TraktAuthUser instance-attribute #

The username being authenticated in Trakt.

rating: NonEmptyStr = '0-100' class-attribute instance-attribute #

Filter series by rating range, with a maximum range of 0-100.

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

Username for the list to import from.

Leave undefined, empty or set to None to use the auth user.

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

Filter series by Trakt genre slug.

years: Optional[YearRange] = None class-attribute instance-attribute #

Filter series by year or year range. (e.g. 2009 or 2009-2015)

limit: PositiveInt = 100 class-attribute instance-attribute #

Limit the number of series to get.

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

Additional parameters to send to the Trakt API.

List#

Import an arbitrary list from Trakt into Sonarr.

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

Type value associated with this kind of import list.

list_name: NonEmptyStr instance-attribute #

Name of the list to import.

The list must be public, or you must have access to the list.

Import media according to popularity-based lists on Trakt.

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

Type value associated with this kind of import list.

list_type: TraktPopularListType = TraktPopularListType.popular class-attribute instance-attribute #

Popularity-based list to import.

Values:

  • trending
  • popular
  • anticipated
  • top_watched_by_week
  • top_watched_by_month
  • top_watched_by_year
  • top_watched_by_alltime
  • recommended_by_week
  • recommended_by_month
  • recommended_by_year
  • recommended_by_alltime

User#

Import a user-level list from Trakt.

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

Type value associated with this kind of import list.

list_type: TraktUserListType = TraktUserListType.user_watch_list class-attribute instance-attribute #

User list type to import.

Values:

  • user_watch_list
  • user_watched_list
  • user_collection_list