Skip to main content

Configuration Files

Configarr uses one required configuration file and one optional file for secrets:

  • config.yml - Required. Contains your main configuration.
  • secrets.yml - Optional. Stores sensitive information when you use !secret.

Usage​

  1. Create config.yml
  2. Decide how you want to provide sensitive values:
    • Use !env and inject environment variables (recommended for containers/Kubernetes)
    • Or use !secret and provide a secrets.yml file
  3. Place your configuration files in the Configarr configuration directory
  4. For Docker/Kubernetes, pass secrets using environment variables or mounted secret files

Configarr will automatically load these configurations on startup and apply them to your Sonarr/Radarr instances.

Configuration Structure​

We try to be mostly compatible with Recyclarr, but with some small differences. We started this fork since Recyclarr V7 and will not always support newer features. Additionally we implement new features which recyclarr does not support at all like custom formats definitions directly in config or support local folders.

Templates​

Configarr supports multiple types of templates:

  1. Recyclarr Templates: Used to define reusable configuration blocks

    • In Recyclarr also named: Pre-Built Configuration Files
    • Documentation: Recyclarr Templates Wiki
    • Location: Place template files in the directory specified by localConfigTemplatesPath

  2. TRaSH-Guides Templates: Standard templates from TRaSH-Guides

  3. URL Templates 1.18.0 Experimental: Load templates directly from HTTP/HTTPS URLs

    • Allows sharing configurations without copying files or forking repositories
    • Supports both Recyclarr format (YAML) and TRaSH-Guides format (JSON) templates
    • Simply provide a URL to a template file in the include section
    • The URL must be accessible via HTTP GET request

Recyclarr Format (YAML):

config.yml
sonarr:
  instance1:
    # ...
    include:
      - template: https://gist.githubusercontent.com/user/abc123/raw/template.yml
      - template: https://example.com/path/to/template.yml
      - template: local-template-name # Still works with local/recyclarr templates

TRaSH-Guides Format (JSON):

config.yml
sonarr:
  instance1:
    # ...
    include:
      - template: https://gist.githubusercontent.com/user/abc123/raw/trash-template.json
        source: TRASH
      - template: https://example.com/path/to/trash-profile.json
        source: TRASH

Notes:

  • Experimental, available since v1.18.0
  • URL templates are processed first, before local and Recyclarr templates
  • Failed URL fetches are logged as warnings and skipped gracefully
  • Recyclarr format templates must be valid YAML files following the Recyclarr template format
  • TRaSH-Guides format templates must be valid JSON files following the TRaSH-Guides quality profile format (must include trash_id field)
  • When loading TRaSH-Guides templates from URLs, specify source: TRASH in the include entry
  • Network requests have a 30-second timeout

Repository URL Configuration​

You can override the default repository URLs for TRaSH-Guides and Recyclarr templates:

config.yml
# Use a custom TRaSH-Guides fork
trashGuideUrl: https://github.com/your-org/fork-TRASH-Guides

# Use a custom Recyclarr templates fork
recyclarrConfigUrl: https://github.com/your-org/fork-recyclarr-configs

# Optional: Specify a custom branch/revision
# trashRevision defaults to 'master'
# recyclarrRevision defaults to a pinned SHA that still has legacy includes/
# (upstream master removed them in Recyclarr v8 — see issue #504)
trashRevision: main
recyclarrRevision: 4ae377bb704fc7fd69a544ad04e91357e0b09f62

Repository URL Changes:

When you change trashGuideUrl or recyclarrConfigUrl in your config:

  • Configarr automatically detects existing cached repositories
  • If the remote URL has changed, it deletes the old repository and re-clones from the new URL
  • The new repository is cloned fresh, avoiding any divergent branch issues
  • If the revision doesn't exist in the new repository, a clear error message is provided
  • No manual cache deletion is required - changes take effect on the next run

Example Scenario:

  1. Start with default TRaSH-Guides repository
  2. Change trashGuideUrl to a custom fork in your config
  3. Run Configarr - it automatically detects the URL change, deletes the old cache, and clones from the new repository
  4. Done! No manual intervention needed.

Error Handling:

If something goes wrong during repository updates:

  • Clear error messages are logged explaining what failed
  • The revision may not exist in the new repository
  • The new URL may not be accessible
  • Check the logs for guidance on how to resolve the issue

Configuration Files Reference​

If you want to deep dive into available values and parameters you can always check the direct source code reference for available configurations: Source Code

config.yml​

The main configuration file that defines your Sonarr and Radarr instances, custom formats, and template includes.

Config.yml
config.yml
# Optional: Override default repositories
#trashGuideUrl: https://github.com/BlackDark/fork-TRASH-Guides
#recyclarrConfigUrl: https://github.com/BlackDark/fork-recyclarr-configs

# Optional: Specify a custom branch/revision
# trashRevision defaults to 'master'
# recyclarrRevision defaults to pinned SHA with legacy includes/ (see issue #504)
#trashRevision: master
#recyclarrRevision: 4ae377bb704fc7fd69a544ad04e91357e0b09f62 # default pin; upstream master dropped legacy includes/ (Recyclarr v8)

# since v1.12.0. Optional. Enable for legacy configuration to clone full repos (trash, recyclarr) instead of sparse.
# Default is false. Setting to true increases storage usage up to 10x.
#enableFullGitClone: true

# since v1.22.0. Optional. Enable compatibility mode for TRaSH-Guides changes from Feb 2026.
# When true: uses old behavior (exclude semantics for CF groups, reversed quality ordering)
# When false (default): uses new behavior (include semantics, display order for qualities)
# See: https://github.com/TRaSH-Guides/Guides/commit/2994a7979d8036a7908a92e2cd286054fd4fcc1b
#compatibilityTrashGuide20260219Enabled: false

# Optional. Silence warnings when a Quality Profile contains CustomFormats marked mutually
# exclusive in TRaSH-Guides conflicts.json. Sync behavior is unchanged; only logs are suppressed.
# Default is false.
#silenceTrashConflictWarnings: true

# since v1.28.0. Optional. Silence warnings when custom_format_groups excludes a CF that TRaSH marks as required.
#silenceRequiredCfGroupExclusionWarnings: true

# Optional: Enable anonymous telemetry tracking of feature usage
# Default is false. Set to true to help improve Configarr by sharing anonymous usage statistics.
telemetry: true

# Optional: Paths for custom formats and templates
localCustomFormatsPath: /app/cfs
localConfigTemplatesPath: /app/templates

# Optional. Custom Format Definitions
customFormatDefinitions:
  - trash_id: example-in-config-cf
    trash_scores:
      default: -10000
    trash_description: "Language: German Only"
    name: "Language: Not German"
    includeCustomFormatWhenRenaming: false
    specifications:
      - name: Not German Language
        implementation: LanguageSpecification
        negate: true
        required: false
        fields:
          value: 4

# With this options you can disable or enable processing for *arrs. Default is enabled
#sonarrEnabled: false
#radarrEnabled: false
#whisparrEnabled: false
#readarrEnabled: false
#lidarrEnabled: false

# Sonarr Configuration
sonarr:
  instance1: # Instance name (can be any unique identifier)
    base_url: http://sonarr:8989 # Sonarr instance URL
    api_key: !secret SONARR_API_KEY # Reference to API key in secrets.yml
    # api_key: !env SONARR_API_KEY # load from environment variable
    # api_key: !file /run/secrets/sonarr_api_key # Load from a file

    # since v1.11.0. You can disable instances. Optional
    # enabled: false

    # since v1.12.0. Optional
    # delete_unmanaged_custom_formats:
    #   enabled: true
    #   ignore: # optional
    #     - some-cf

    # since v1.18.0. Optional
    # delete_unmanaged_quality_profiles:
    #   enabled: true
    #   ignore: # optional
    #     - some-qp

    # experimental since v1.14.0. Optional
    # root_folders:
    #   - /mnt/media/series

    # experimental since v1.14.0. Optional
    # delay_profiles:
    #   default:
    #     enableUsenet: true
    #     enableTorrent: false
    #     preferredProtocol: usenet
    #     usenetDelay: 10
    #     torrentDelay: 0
    #     bypassIfHighestQuality: false
    #     bypassIfAboveCustomFormatScore: false
    #     minimumCustomFormatScore: 0
    #   # Lidarr nightly (plugin support): use items instead of enableUsenet/enableTorrent (since v1.30.1)
    #   # default:
    #   #   items:
    #   #     - name: Usenet
    #   #       protocol: UsenetDownloadProtocol
    #   #       allowed: true
    #   #       delay: 2
    #   #     - name: Torrent
    #   #       protocol: TorrentDownloadProtocol
    #   #       allowed: true
    #   #       delay: 0
    #   #   bypassIfHighestQuality: true
    #   additional:
    #     - enableUsenet: true
    #       enableTorrent: false
    #       preferredProtocol: usenet
    #       usenetDelay: 10
    #       torrentDelay: 0
    #       bypassIfHighestQuality: false
    #       bypassIfAboveCustomFormatScore: false
    #       minimumCustomFormatScore: 0
    #       order: 1
    #       tags:
    #         - delayprofiletest

    # experimental. Optional. Defined list is complete desired state; unmatched server profiles are deleted.
    # release_profiles:
    #   - name: HEVC only
    #     enabled: true
    #     required:
    #       - hevc
    #       - x265
    #     ignored:
    #       - xvid
    #     # indexer: MyIndexer
    #     tags:
    #       - hevc

    quality_definition:
      type: series # Quality definition type for Sonarr

    include: # Template includes
      - template: sonarr-cf
      - template: sonarr-quality
      - template: d1498e7d189fbe6c7110ceaabb7473e6
        source: TRASH # RECYCLARR (default) or TRASH

      # WEB-1080p (recyclarr template)
      - template: sonarr-quality-definition-series
      - template: sonarr-v4-quality-profile-web-1080p
      - template: sonarr-v4-custom-formats-web-1080p

      # (experimental) since v1.18.0. Load template from URL
      # - template: https://gist.githubusercontent.com/user/abc123/raw/template.yml

    # experimental available in all *arr
    #media_management: {}

    # experimental available in all *arr
    #media_naming_api: {}

    # experimental available in all *arr
    #ui_config: {}

    # naming from recyclarr: https://recyclarr.dev/wiki/yaml/config-reference/media-naming/
    #media_naming: {}
    # (experimental) Manage download clients
    #download_clients:
    #  - name: "Primary qBittorrent"
    #    type: qbittorrent
    #    enable: true
    #    priority: 1
    #    remove_completed_downloads: true
    #    remove_failed_downloads: true
    #    tags:
    #      - "4K"
    #      - "High Quality"
    #    fields:
    #      host: qbittorrent
    #      port: 8080
    #      use_ssl: false
    #      url_base: /
    #      username: sonarr
    #      password: changeme
    #      tv_category: series-4k
    #
    #  # Always update password fields even when they match the server
    #  update_password: false
    #  # Delete unmanaged download clients
    #  delete_unmanaged:
    #    enabled: true
    #    ignore:
    #      - "Manual Test Client"
    #  # Global download client configuration
    #  config:
    #    download_client_working_folders: "/downloads,/tmp"
    #    enable_completed_download_handling: true
    #    auto_redownload_failed: false
    #    auto_redownload_failed_from_interactive_search: false
    #    # Radarr only: Check interval for finished downloads (in minutes)
    #    check_for_finished_download_interval: 5
    #    # Note: auto_redownload_failed_from_interactive_search is not available in Whisparr

    # (experimental) custom_format_groups since v1.12.0; expanded cf-group options since v1.28.0
    # allows using the cf-groups from TRaSH-Guide.
    custom_format_groups:
      - trash_guide:
          - id: c4735e1d02e8738044ad4ad1bf58670c # Multiple CFs, default only required=true are loaded
            #include_unrequired: true # if you want to load all set this to true
        assign_scores_to:
          - name: WEB-1080p

    custom_formats: # Custom format assignments
      - trash_ids:
          - 47435ece6b99a0b477caf360e79ba0bb # x265 (HD)
        assign_scores_to:
          - name: WEB-1080p
            score: 0
      - trash_ids:
          - a3d82cbef5039f8d295478d28a887159 # block HDR10+
          - 2b239ed870daba8126a53bd5dc8dc1c8 # block DV HDR10+
        assign_scores_to:
          - name: WEB-1080p
            score: -10000
      - trash_ids:
          - example-in-config-cf # custom format defined in config.yml
        assign_scores_to:
          - name: WEB-1080p
            score: -5000

    quality_profiles:
      - name: WEB-1080p
        upgrade:
          min_format_score: 10000

    # Ability to rename quality profiles
    # renameQualityProfiles:
    # - from: WEB-1080p
    #   to: RenamedProfile

    # Ability to clone profiles
    # cloneQualityProfiles:
    #   - from: RenamedExampleProfile
    #     to: ClonedProfile

# Radarr Configuration
radarr:
  instance1: # Instance name (can be any unique identifier)
    base_url: http://radarr:7878 # Radarr instance URL
    api_key: !secret RADARR_API_KEY # Reference to API key in secrets.yml

    quality_definition:
      type: movie # Quality definition type for Radarr

    include:
      # Comment out any of the following includes to disable them
      - template: radarr-quality-definition-movie
      - template: radarr-quality-profile-hd-bluray-web
      - template: radarr-custom-formats-hd-bluray-web

    custom_formats: # Custom format assignments
      - trash_ids:
          - 9f6cbff8cfe4ebbc1bde14c7b7bec0de # IMAX Enhanced
        assign_scores_to:
          - name: HD Bluray + WEB
            score: 0

    quality_profiles:
      - name: HD Bluray + WEB
        # Support added with 1.7.0. Not support in all *arr applications. Check the application if it is supported.
        language: Any # The name must match available names in *arr
        # Reset existing CustomFormats scores on profile
        reset_unmatched_scores:
          enabled: true
        upgrade:
          allowed: true
          until_quality: Remux-1080p
          until_score: 10000 # Upgrade until score
          min_format_score: 100 # The minimum increment to trigger an upgrade
        min_format_score: 100 # The most important custom format needed to download
        # Score set from TRaSH-Guide to use
        #score_set: anime-radarr
        # Sorting order of qualities in profile. Either top or bottom
        #quality_sort: top
        # How to group and sort profiles
        qualities:
          - name: Remux-1080p
            qualities:
              - Bluray-1080p
              - Remux-1080p
          - name: WEB 1080p
            qualities:
              - WEBDL-1080p
              - WEBRip-1080p
              - HDTV-1080p
          - name: Bluray-720p
          - name: WEB 720p
            qualities:
              - WEBDL-720p
              - WEBRip-720p
              - HDTV-720p
          - name: Bluray-576p
          - name: Bluray-480p
          - name: WEB 480p
            qualities:
              - WEBDL-480p
              - WEBRip-480p
          - name: DVD
          - name: SDTV

# experimental support: check https://configarr.rayak.de/docs/configuration/experimental-support
whisparr: {}

# experimental support: check https://configarr.rayak.de/docs/configuration/experimental-support
readarr: {}

# experimental support: check https://configarr.rayak.de/docs/configuration/experimental-support
lidarr: {}

secrets.yml​

Store sensitive information like API keys in this file when using !secret. Never commit this file to version control.

secrets.yml
SONARR_API_KEY: your_sonarr_api_key_here
RADARR_API_KEY: your_radarr_api_key_here

Multiple secrets and globs 1.21.0

SECRETS_LOCATION can be a comma-separated list of files and/or glob patterns. All matched files are loaded and merged; later files override earlier ones.

SECRETS_LOCATION=./config/secrets.yml,./config/overrides.yml
SECRETS_LOCATION=./config/secrets/*.yml

If a single non-glob path is provided and the file doesn't exist, Configarr fails on startup. If a glob has no matches, it continues with empty secrets and logs a warning.

Value sources (!secret, !env, !file)​

Configarr supports custom YAML tags to load values from different sources:

  • !secret: Loads a key from secrets.yml
  • !env: Loads an environment variable
  • !file: Loads the contents of a file
config.yml
sonarr:
  series:
    base_url: !env SONARR_URL
    api_key: !env SONARR_API_KEY

radarr:
  default:
    base_url: !secret RADARR_URL
    api_key: !secret RADARR_API_KEY

For Kubernetes, using !env is usually the easiest approach because values can come directly from Kubernetes Secrets via container environment variables.

Enable/Disable​

You can configure enabled *Arr instance with options in the config.yml file. Default everything is true.

# true or false
sonarrEnabled: false
radarrEnabled: false
whisparrEnabled: false
readarrEnabled: false
lidarrEnabled: false

# You can also disable on per instance basis
sonarr:
  instance1:
    # ...
    enabled: false

Telemetry 1.16.0​

Configarr can optionally collect anonymous telemetry data to help improve the application. This includes information about which features are being used, but no personal data, API keys, or configuration details are collected.

To enable telemetry, add the following to your config.yml:

telemetry: true

Note: Telemetry is disabled by default and is completely opt-in. See Telemetry

TRaSH CustomFormat conflicts 1.26.0​

Configarr parses conflicts.json from TRaSH-Guides and logs a warning when a Quality Profile is configured with two or more CustomFormats that TRaSH marks as mutually exclusive. Sync behavior is not changed — the warning is informational only, so you can review whether the combination is intentional.

The check runs automatically for Radarr and Sonarr instances whenever conflicts.json is available in the TRaSH-Guides repository.

Silence conflict warnings 1.27.0​

If you intentionally configure conflicting CustomFormats (or simply want quieter logs), set the top-level flag to skip the check:

silenceTrashConflictWarnings: true

Default is false. Sync behavior is identical either way — only the warning log is suppressed.

Sharing download client config with YAML anchors 1.23.0​

You can avoid repeating the same download client settings by using YAML anchors and merge keys:

  • Anchors (&name): Define a block once and give it a name.
  • Aliases (*name): Reuse that block by reference.
  • Merge key (<<: *name): Merge the anchored block into the current mapping; any keys you add after it override the anchored values.

This works only when merge keys are enabled. Set the environment variable CONFIGARR_ENABLE_MERGE=true (see Environment Variables); otherwise << is not interpreted as a merge key and your config may fail to parse or behave unexpectedly.

Example: shared base with anchors and merge

config.yml (requires CONFIGARR_ENABLE_MERGE=true)
x-download-clients:
  # Define an anchor for shared instance
  qb_base: &qb_base
    name: "qBit"
    type: qbittorrent
    enable: true
    priority: 1
    remove_completed_downloads: true
    remove_failed_downloads: true
    # YAML does a shallow merge, thus we must declare another anchor for the nested dictionary if we plan to override values in it
    fields: &qb_fields
      host: qbittorrent
      port: 8080
      use_ssl: false
      username: admin
      password: changeme

sonarr:
  instance1:
    base_url: http://sonarr:8989
    api_key: !secret SONARR_API_KEY
    download_clients:
      data:
        - <<: *qb_base
          fields:
            <<: *qb_fields
            tv_category: series
          tags: ["sonarr"]
        # Reuse same base, override name and fields
        - <<: *qb_base
          name: "qBit 4K"
          fields:
            <<: *qb_fields
            tv_category: series-4k
          tags: ["4K"]
      update_password: false
      delete_unmanaged:
        enabled: true
        ignore: ["Manual Test Client"]
      config:
        enable_completed_download_handling: true
        auto_redownload_failed: false

The anchor (qb_base: &qb_base) can live at any level, inside a different key (as above), or at the top level. Each list item merges *qb_base with <<: and then overrides properties as needed. Without CONFIGARR_ENABLE_MERGE=true, use fully inline entries (no <<) as in the example at the start of this section.

Quality Definition / Size​

Quality definitions control the min/max/preferred file sizes for each quality level. There are three ways to configure them:

Method 1: Reference a TRaSH-Guides definition by type (classic)​

The type value must match the filename (without .json) in the TRaSH-Guides quality-size directory.

Radarr — available type values:

typeDescription
movieStandard movie sizes
animeAnime movie sizes
sqp-streamingStreaming Preferred quality profile sizes
sqp-uhdUHD Streaming quality profile sizes

Sonarr — available type values:

typeDescription
seriesStandard TV series sizes
animeAnime series sizes
radarr:
  instance1:
    quality_definition:
      type: movie # matches radarr/quality-size/movie.json
      preferred_ratio: 0.5 # optional: 0.0 (min) to 1.0 (max), default uses TRaSH preferred

sonarr:
  instance1:
    quality_definition:
      type: series # matches sonarr/quality-size/series.json

Hint: type (filename-based) may be deprecated in favor of trash_id in a future version. See GitHub Issue #155.

Method 2: Include a quality definition via include (auto-detected)​

When you include a TRaSH JSON file with source: TRASH, Configarr automatically detects whether it is a quality profile or a quality definition and routes it accordingly. This works for both named trash_id references and URL templates.

By trash_id:

radarr:
  instance1:
    include:
      - template: aed34b9f60ee115dfa7918b742336277 # movie quality definition
        source: TRASH
        preferred_ratio: 0.5 # optional: only applies when include resolves to a QD

sonarr:
  instance1:
    include:
      - template: bef99584217af744e404ed44a33af589 # series quality definition
        source: TRASH

By URL:

radarr:
  instance1:
    include:
      - template: https://raw.githubusercontent.com/TRaSH-Guides/Guides/master/docs/json/radarr/quality-size/movie.json
        source: TRASH
        preferred_ratio: 0.5

trash_id reference table:

Arrtypetrash_id
Radarrmovieaed34b9f60ee115dfa7918b742336277
Radarranimec2aa9540a57d273a9e03a538efe0ca1b
Radarrsqp-streaming8f1391784833965c476bb6aee95fe328
Radarrsqp-uhdda8c8c0268b2f304be588132831543d2
Sonarrseriesbef99584217af744e404ed44a33af589
Sonarranime387e6278d8e06083d813358762e0ac63

Method 3: Manual quality sizes​

Override individual quality sizes directly — useful for fine-tuning without loading a full TRaSH definition. Can be combined with either method above (manual entries are applied last and take precedence for matching quality names).

sonarr:
  instance1:
    quality_definition:
      qualities:
        - quality: "HDTV-720p" # must match the name shown in the *arr UI
          title: AdjustedName # optional: rename in UI
          min: 17.1
          preferred: 500
          max: 1000

# Or in a template file:
quality_definition:
  qualities:
    - quality: "HDTV-1080p"
      min: 20
      preferred: 500
      max: 1000

Notes:

  • preferred_ratio (0.0 – 1.0) interpolates between min and max to compute preferred. It applies to type-based and include-based loading; it has no effect on manual qualities.
  • preferred_ratio on include items applies only to that specific include.
  • Merge order: TRaSH/Recyclarr templates → local templates → config file (quality_definition.qualities last).
  • Only supported for Radarr and Sonarr. Not available for Lidarr, Readarr, Whisparr.
  • Available since v1.9.0. Include-based QD detection available since v1.x.0 (TBD).

Media Naming​

You can use the predefined naming configurations from TRaSH-Guide like in recyclarr with the media_naming key.

The configuration values differs between Radarr and Sonarr.

Radarr

radarr:
  instance1:
    # Media Naming Configuration
    media_naming:
      folder: default
      movie:
        rename: true
        standard: standard
PropertyDescriptionDefault
folderKey for "Movie Folder Format". Check debug logs or TRaSH-Guide for values.Not synced
movie.renameIf set to true, this enables the "Rename Movies" checkbox in the Radarr UI.Not synced
movie.standardKey for "Standard Movie Format". Check debug logs or TRaSH-Guide for values.Not synced

All configurations above directly affect the "Movie Naming" settings under Settings > Media Management in the Radarr UI. If a property is not specified, Configarr will not sync that setting, allowing manual configuration.

Sonarr

sonarr:
  instance1:
    # Media Naming Configuration
    media_naming:
      series: default
      season: default
      episodes:
        rename: true
        standard: default
        daily: default
        anime: default
PropertyDescriptionDefault
seriesKey for "Series Folder Format". Check debug logs or TRaSH-Guide for values.Not synced
seasonKey for "Season Folder Format". Check debug logs or TRaSH-Guide for values.Not synced
episodes.renameIf set to true, this enables the "Rename Episodes" checkbox in the Sonarr UI.Not synced
episodes.standardKey for "Standard Episode Format". Check debug logs or TRaSH-Guide for values.Not synced
episodes.dailyKey for "Daily Episode Format". Check debug logs or TRaSH-Guide for values.Not synced
episodes.animeKey for "Anime Episode Format". Check debug logs or TRaSH-Guide for values.Not synced

All configurations above directly affect the "Episode Naming" settings under Settings > Media Management in the Sonarr UI. If a property is not specified, Configarr will not sync that setting, allowing manual configuration.

Quality Profile​

This is general structure of a profile which can be directly in the config or in templates. Some fields could differ between different *arrs if some features between mismatch. Mostly those should be the same.

# ...

sonarr:
  instance1:
    # ...

    quality_profiles:
      - name: ExampleInConfigProfile
        reset_unmatched_scores:
          enabled: true # enable to reset scores
        upgrade:
          allowed: true # enable to allow updates
          until_quality: WEB 2160p # update until quality
          until_score: 1000 # Upgrade until score
          min_format_score: 5 # Minimum increment for upgrade
        min_format_score: 0 # Minimum custom format needed to download
        quality_sort: top # enable to allow updates
        qualities: # qualtities enabled in the profile. Can be groups.
          - name: Remux-2160p
          - name: WEB 2160p # This a group
            qualities:
              - WEBDL-2160p
              - WEBRip-2160p
          - name: Remux-1080p
          - name: WEB 1080p
            qualities:
              - WEBDL-1080p
              - WEBRip-1080p

Sonarr v5 stores size limits on each quality-profile quality instead of globally. Keep quality_definition for a shared default, then set quality_sizes on a profile only where it needs a different value. Per-profile values take precedence field by field; omitted fields inherit the global default, or keep Sonarr's current value when neither form configures that field. quality_sizes requires Sonarr v5; Configarr reports an error before applying changes if it is used with Sonarr v4.

sonarr:
  instance1:
    quality_definition:
      qualities:
        - quality: WEBDL-1080p
          min: 5
          preferred: 50
          max: 199.9

    quality_profiles:
      - name: WEB-1080p
        quality_sizes:
          - quality: WEBDL-1080p
            min: 0
            preferred: 75

Quality selectors accept the quality name or display title shown in Sonarr. Only the configured fields are changed; zero is a valid size value.

Quality Profile Rename​

Support has been added to allow renaming quality profiles. This is useful if you use existing templates for example from TRaSH-Guides but want to adjust the naming to your liking.

We achieve the renaming by modifying all names in the quality_profiles fields and custom formats score mappings.

# ...

sonarr:
  instance1:
    # ...

    # Ability to rename profiles
    renameQualityProfiles:
      - from: ExampleProfile # must be the exact name of the existing profile
        to: RenamedExampleProfile # will be the new profile

Notes:

  • not supported in templates and will therefore not be merged!
  • rename order will be displayed in DEBUG log like: DEBUG [16:37:09.377]: Will rename quality profiles in this order: 'ExampleProfile' -> 'RenamedExampleProfile','[German] HD Bluray + WEB' -> 'RenamedProfile'
  • experimental, available since v1.10.0

Quality Profile Cloning​

Support has been added to allow cloning quality profiles. This is useful if you use existing templates for example from TRaSH-Guides but want to duplicate and slightly adjust some Custom Format scores or mappings.

We achieve the clone by duplicating all quality profiles and duplicating all profile references in the custom formats.

tip

The ordering of rename and clone is important. At the moment we rename first and then clone!

# ...

sonarr:
  instance1:
    # ...

    # Ability to clone profiles
    cloneQualityProfiles:
      - from: ExampleProfile # must be the exact name of the existing profile
        to: ClonedProfile1 # will be the new profile

Notes:

  • not supported in templates and will therefore not be merged!
  • clone order will be displayed in DEBUG log
  • experimental, available since v1.10.0

Custom Formats Definitions​

Custom formats can be defined in two ways:

  1. Direct in config.yml: Define custom formats directly in your configuration file
  2. Separate files: Store custom formats in separate files in the localCustomFormatsPath directory
  3. Local templates: Store custom formats in local templates folder which can be included per instance (at the moment only for local templates and not recyclarr git templates)

Example custom format definition:

config.yml
# Directly in the main config.yml
customFormatDefinitions:
  - trash_id: custom-de-only # Unique identifier
    trash_scores:
      default: -10000 # Default score for this format
    trash_description: "Language: German Only"
    name: "Language: Not German"
    includeCustomFormatWhenRenaming: false
    specifications:
      - name: Not German Language
        implementation: LanguageSpecification
        negate: true
        required: false
        fields:
          value: 4
# ...
local-templates/template1.yml
# or in templates which can be included per instance
customFormatDefinitions:
  - trash_id: custom-de-only2 # Unique identifier
    trash_scores:
      default: -10000 # Default score for this format
    trash_description: "Language: German Only 2"
    name: "Language: Not German"
    includeCustomFormatWhenRenaming: false
    specifications:
      - name: Not German Language
        implementation: LanguageSpecification
        negate: true
        required: false
        fields:
          value: 4
# ...

Custom Formats​

  • since v1.13.0 CustomFormats can now also be assigned to Quality Profiles which only exist on the server and are not configured in the config file or included. This means you can only define the custom format mapping and do not have to provide quality_profiles if they already exist on the server.

    CustomFormats with unmanaged QualityProfiles
    CustomFormats with unmanaged QualityProfiles
    sonarr:
      instance1:
        base_url: http://sonarr:8989
        api_key: !secret SONARR_API_KEY

        # since v1.13.0. You can assign custom formats to quality profiles which are only managed on the server
        custom_formats:
          - trash_ids:
              - 47435ece6b99a0b477caf360e79ba0bb # x265 (HD)
            assign_scores_to:
              - name: Any

        # 'Any' already exists on server
        # quality_profiles:
        #   - name: Any
        #     # ...

  • 1.16.0 CustomFormats and CustomFormatGroups do not have to be assigned to a quality profile. If not assigned to a profile they will still be created on the *arr instance.

Cleanup / Deleting CustomFormats​

You can now enable the option to delete all custom formats which are not managed and used in the quality profiles. Additionally you can provide exceptions which should be ignored from deletions.

# ...

sonarr:
  instance1:
    # ...

    # (experimental) since v1.12.0. Optional
    delete_unmanaged_custom_formats:
      enabled: true
      ignore: # optional
        - some-cf

Notes:

  • experimental, available since v1.12.0

Cleanup / Deleting QualityProfiles​

You can now enable the option to delete all quality profiles which are not managed by configarr. Additionally you can provide exceptions on which quality profile(s) should be ignored from deletion.

# ...
sonarr:
  instance1:
    # ...
    # (experimental) since v1.18.0. Optional
    delete_unmanaged_quality_profiles:
      enabled: true
      ignore: # optional
        - some-qp

Notes:

  • experimental, available since v1.18.0

Tags 1.34.0​

Every instance can manage Tags directly. The tags block is a plain list of tag labels which are created on the server when they do not exist yet, and delete_unmanaged_tags prunes the server tags that are not managed by your config.

# ...
sonarr:
  instance1:
    # ...
    # since v1.34.0. Optional
    tags:
      - configarr
      - vip
    # since v1.34.0. Optional
    delete_unmanaged_tags:
      enabled: true
      ignore: # optional
        - some-tag

Notes:

  • available since v1.34.0 for Sonarr, Radarr, Lidarr, Readarr and Whisparr. Prowlarr has the same block, see Prowlarr
  • Tag labels are matched case-insensitively: a label that only differs in casing resolves to the existing server tag instead of creating a second one
  • tags is optional. The tags referenced by your managed features (delay_profiles, release_profiles, root_folders, download_clients) are created as well, so listing them here is a declarative way to see and keep all your labels in one place
  • delete_unmanaged_tags deletes every server tag which is neither listed under tags, nor listed under ignore, nor referenced by one of the managed features listed above. If it stops part-way (a server error after some tags were already deleted), the report still lists the deletions that went through
  • A tag that is still in use by something configarr does not manage (for example an import list, notification or indexer) cannot be deleted. On media *arrs the tag is left alone and a warning is logged, so the rest of the instance still syncs. On Prowlarr every tag-bearing resource is managed, so this case fails the Prowlarr instance instead
  • Prowlarr keeps its own set of referencing features: its tags are also read from applications, indexers and indexer_proxies
  • A dry run (DRY_RUN=true) never creates or deletes tags; it only reports what it would do
  • Both keys work the same way whether they come from your config or from a template: a Recyclarr, URL or local template that sets delete_unmanaged_tags.enabled: true switches tag pruning on for every instance including it. Review templates from third parties for this key before including them
  • The instance-level tags list takes labels only. Inside the per-feature blocks (download_clients, Prowlarr applications / indexers / indexer_proxies) a raw server id is still accepted but is deprecated — it logs a warning and may be removed in a future release. Use labels everywhere

CustomFormatGroups 1.12.0​

Support has been added to allow using the TRaSH-Guide custom format groups: see here. Those are logically bundled together CustomFormats which will be applied together. TRaSH-Guide describes optional CFs and defaults per cf-groups.

Version notes

Listing TRaSH cf-groups under custom_format_groups has been supported since v1.12.0 (experimental). The expanded TRaSH cf-group handling in this section—including additive include, default/include_unrequired/exclude behavior, silenceRequiredCfGroupExclusionWarnings, and trash_cfgroup_* auto-group overrides—requires v1.28.0 or newer.

When you reference a group (custom_format_groups), Configarr expands TRaSH IDs into CF assignments like this:

  • Default expansion (no include key): includes each CF in the group where required: true or default: true / "true" (same idea as TRaSH default-checked optional CFs).
  • include_unrequired: true: includes every CF listed in the group JSON for that group reference (full group contents).
  • include: optional additive list of { id: <CF trash_id> }. Listed IDs are added on top of the base selection (they must exist in the group). This is mainly useful to add non-default optional CFs without enabling full include_unrequired.
  • exclude: optional list of { id: <CF trash_id> } removed after selection. If the same trash_id appears in both include and exclude, exclude wins.
  • Listing an exclude id that TRaSH marks as required: true logs a warning by default (you intentionally omit that CF). Set top-level silenceRequiredCfGroupExclusionWarnings: true to suppress that warning (sync behavior unchanged).

The quality_profiles block inside TRaSH cf-group JSON does not apply to custom_format_groups in config — it is only used when Configarr auto-applies default groups for included TRaSH quality profiles. For that automatic path, you can configure defaults at the instance level and override per TRaSH include item.

TRaSH Auto CF-Group Overrides 1.28.0 (Experimental)​

This feature is experimental, shipped in v1.28.0, and may change in future releases.

When using include with source: TRASH (quality profile JSON), Configarr auto-loads CFs from TRaSH default CF-groups. You can now influence this behavior:

  • Instance-level defaults under trash_cfgroup_config (apply to all TRaSH profile includes in that instance)
  • Include-item overrides (apply only to one include entry)

Precedence:

  1. Base auto selection from TRaSH default groups (required, plus optional default CFs when enabled)
  2. trash_cfgroup_include_unrequired (if true, start from all CFs in matched groups)
  3. trash_cfgroup_include_cfs (if provided, additive merge on top of current selection)
  4. trash_cfgroup_exclude_cfs (always last, wins over include)

If a required CF is excluded, Configarr logs a warning by default (same warning control via silenceRequiredCfGroupExclusionWarnings).

# Optional: suppress warnings when excluding required CFs from a group (see above)
silenceRequiredCfGroupExclusionWarnings: false

# ...

sonarr:
  instance1:
    # ...

    # Experimental instance-level defaults for TRaSH auto CF-group loading
    trash_cfgroup_config:
      # optional: true (default)
      include_optional: true
      # optional: false (default)
      include_unrequired: false
      # optional: [] (default)
      include_cfs:
        - id: example-cf-id
      # optional: [] (default)
      exclude_cfs:
        - id: example-cf-id

    # (experimental) custom_format_groups since v1.12.0; expanded cf-group options below since v1.28.0
    # allows using the cf-groups from TRaSH-Guide.
    custom_format_groups:
      - trash_guide:
          - id: c4735e1d02e8738044ad4ad1bf58670c
            # include_unrequired: true   # load every CF in this group
            # include:                   # add specific CF trash_ids
            #   - id: abc...
            # exclude:                   # drop CFs after selection (wins over include)
            #   - id: def...
        assign_scores_to:
          - name: MyProfile
            # score: 0 # optional score for all CFs from this group row; override per CF via custom_formats

    include:
      - template: 2b90e905c99490edc7c7a5787443748b
        source: TRASH
        # Experimental per-include overrides (override instance defaults)
        trash_cfgroup_include_optional: false
        trash_cfgroup_include_unrequired: false
        trash_cfgroup_include_cfs:
          - id: some-cf-id
        trash_cfgroup_exclude_cfs:
          - id: another-cf-id

Notes:

  • experimental — custom_format_groups since v1.12.0; expanded TRaSH cf-group behavior and trash_cfgroup_* overrides in this section since v1.28.0.

TRaSH-Guides Breaking Changes (Feb 2026)​

Breaking Change

TRaSH-Guides made significant changes to their JSON structure in February 2026, affecting both CF group semantics and quality profile ordering.

For detailed information about what changed, backward compatibility options, and version matrix, see the TRaSH-Guides Breaking Changes FAQ.

With version v1.22.0 the new format will be processed.

RootFolders​

With Configarr you can configure the root folders directly. Just specify the list of your folders and Configarr will delete and create them as specified in the list.

# ...

sonarr:
  instance1:
    # ...
    # (experimental) since v1.14.0
    root_folders:
      - /mnt/media/series

Notes:

  • experimental, available since v1.14.0

Delay Profiles​

You can configure and sync Delay Profiles directly in your config. This allows you to manage the download delay logic for Usenet and Torrent protocols, including protocol preference, delays, and tag-based rules.

A delay profile without any tags is considered the default profile. Any other profiles with tags are additional profiles.

yourarr:
  instance1:
    # (experimental) since v1.14.0
    delay_profiles:
      default:
        enableUsenet: true
        enableTorrent: false
        preferredProtocol: usenet
        usenetDelay: 10
        torrentDelay: 0
        bypassIfHighestQuality: false
        bypassIfAboveCustomFormatScore: false
        minimumCustomFormatScore: 0
      additional:
        - enableUsenet: false
          enableTorrent: true
          preferredProtocol: torrent
          usenetDelay: 0
          torrentDelay: 20
          bypassIfHighestQuality: true
          bypassIfAboveCustomFormatScore: false
          minimumCustomFormatScore: 0
          order: 2
          tags:
            - mytag

Protocol items (Lidarr nightly) 1.30.1​

Lidarr nightly (plugin support) replaced the legacy Usenet/Torrent flags with a protocol items list. Custom protocols from plugins (for example Tubifarry) appear as extra entries in that list.

lidarr:
  instance1:
    delay_profiles:
      default:
        items:
          - name: Usenet
            protocol: UsenetDownloadProtocol
            allowed: true
            delay: 2
          - name: Torrent
            protocol: TorrentDownloadProtocol
            allowed: true
            delay: 0
          # Plugin protocols (example):
          # - name: Youtube
          #   protocol: YoutubeDownloadProtocol
          #   allowed: false
          #   delay: 0
        bypassIfHighestQuality: true
        bypassIfAboveCustomFormatScore: true
        minimumCustomFormatScore: 0

YAML key Items is accepted as an alias for items.

Backward compatible: existing configs that only set enableUsenet / enableTorrent / preferredProtocol / usenetDelay / torrentDelay keep working for Sonarr, Radarr, Whisparr, Readarr, and Lidarr stable. If items is set (non-empty), configarr sends the items payload and does not send the legacy protocol fields for that profile.

Notes:

  • experimental, available since v1.14.0; protocol items since v1.30.1
  • Supported for Sonarr, Radarr, Whisparr, Lidarr, and Readarr (if the API supports it)
  • If a delay profile exists on the server but not in your config, it will be deleted
  • If a delay profile is in your config but not on the server, it will be created (if supported)
  • If a delay profile differs, it will be updated

See example Radarr API DelayProfile for legacy fields. Lidarr nightly uses items instead.

Release Profiles​

Sync Servarr Release Profiles (Must Contain / Must Not Contain, indexer scope, tags). Preferred words inside release profiles were replaced by Custom Formats; this block covers the remaining required/ignored terms.

If release_profiles is omitted, Configarr does not touch them. If it is present, the list is the complete desired state: missing profiles are created, matching ones updated, and any server profile not in the list is deleted. An empty list ([]) deletes all of them.

yourarr:
  instance1:
    release_profiles:
      - name: HEVC only # optional; ignored on Lidarr/Readarr
        enabled: true # default true
        required: # Must Contain
          - hevc
          - x265
          - /h\.?265/i
        ignored: # Must Not Contain
          - xvid
        indexer: MyIndexer # optional indexer name; omitted = any indexer
        # Sonarr v5 only: use `indexers` instead of `indexer` to select multiple by name.
        # An empty list, or omitting both selector fields, means any indexer.
        # indexers: [Usenet, Torrents]
        tags:
          - hevc # tag labels; created if missing. Empty = all series/movies
        # Sonarr v5 only; omitted policy fields keep their current server values on update.
        # excluded_tags: [anime] # overrides `tags` when a series has a matching tag
        # air_date_restriction: true
        # air_date_grace_period: 12 # hours
        # allow_season_pack_without_all_episodes_aired: true

Notes:

  • experimental
  • Supported for Sonarr, Radarr, Whisparr, Lidarr, and Readarr
  • Match by name when the *arr API has that field and you set one. Otherwise match by content (enabled, required, ignored, indexer, tags). A nameless config entry matches a named server profile with the same content and leaves the name in place.
  • Lidarr and Readarr have no name field, so a change to required/ignored/tags/indexer is treated as a new profile (delete + create).
  • Duplicate names (or duplicate nameless content) in the list fail validation
  • Unknown indexer names fail validation
  • Sonarr v5 also supports multiple indexers, excluded_tags, and air-date/season-pack policies. indexer and indexers cannot be used together; indexers: [] means any indexer, as on the Sonarr server.
  • These added options require Sonarr v5. Configarr rejects them on Sonarr v4 rather than silently dropping them.
  • excluded_tags takes precedence over tags; a label cannot be present in both lists. air_date_grace_period is measured in hours. Omitted v5 policy fields preserve the existing server value on update and use Sonarr's default on create.
  • Preferred-word scoring still belongs in custom_formats / quality_profiles

Download Clients 1.19.0​

Configarr can (experimentally) manage the Download Clients configured in your *Arr applications (for example qBittorrent, Transmission, SABnzbd, etc.).

  • Create download clients that exist in the config but not in the *Arr instance
  • Optionally delete unmanaged download clients
  • Manage global download client configuration settings since v1.19.0
config.yml (inline, no top-level)
sonarr:
  instance1:
    base_url: http://sonarr:8989
    api_key: !secret SONARR_API_KEY

    # (experimental) Manage Sonarr download clients
    download_clients:
      data:
        - name: "qBit 4K"
          type: qbittorrent
          enable: true
          priority: 1
          remove_completed_downloads: true
          remove_failed_downloads: true
          tags:
            - "4K" # Tag name (auto-resolved to ID)
          fields:
            host: qbittorrent
            port: 8080
            use_ssl: false
            url_base: /
            username: sonarr
            password: changeme
            tv_category: series-4k
       # Set to true to always update password otherwise existing passwords will not be updated because we can not retrieve existing passwords
       update_password: false
      # Delete unmanaged download clients
      delete_unmanaged:
        enabled: true
        ignore:
          - "Manual Test Client"
      # (since v1.19.0) Global download client configuration
      config:
        enable_completed_download_handling: true
        auto_redownload_failed: false
        auto_redownload_failed_from_interactive_search: false
        # Radarr only: Check interval for finished downloads (in minutes)
        # check_for_finished_download_interval: 1

Download Client Configuration 1.19.0​

The config section allows you to manage global download client settings. Please check the *Arr-specific API for supported fields (in the REST APIs under DownloadClientConfig).

  • convert the camelCase typed fields like enableCompletedDownloadHandling to snake_case: enable_completed_download_handling

Note: Instance-specific fields (like check_for_finished_download_interval for Radarr) are automatically filtered based on the *Arr type. Unsupported fields are safely ignored.

Remote Path Mappings 1.20.0​

Remote path mappings allow you to remap remote paths from your download clients to local paths that your *Arr applications can access. This is useful when your download client is running on a different machine or in a container with different mount paths.

config.yml
radarr:
  instance1:
    download_clients:
      remote_paths:
        - host: "transmission"
          remote_path: "/downloads/complete"
          local_path: "/data/media/downloads/complete"
        - host: "192.168.1.100"
          remote_path: "/torrents"
          local_path: "/mnt/torrents"

Key Points:

  • host: The hostname or IP address of the download client
  • remote_path: The path as seen by the download client (must be unique combined with host)
  • local_path: The path as accessible by the *Arr application
  • Mappings are matched by host + remote_path combination (must be unique)
  • Existing mappings with matching host+remote_path will be updated with new local_path
  • Mappings that exist on the server but not in config will be deleted

For more details, check the *Arr-specific API documentation under the RemotePathMapping resource endpoint.

Prowlarr 1.31.0​

Prowlarr uses a dedicated top-level prowlarr: block (see Experimental support › Prowlarr). Under each instance it can manage tags, sync_profiles, indexer_proxies, indexers, applications and download_clients (synced in that order). Each list section takes an optional delete_unmanaged: { enabled, ignore }.

applications manages the apps Prowlarr syncs its indexers to:

config.yml
prowlarr:
  main:
    base_url: http://prowlarr:9696
    api_key: !secret PROWLARR_API_KEY

    applications:
      data:
        - name: Sonarr
          type: Sonarr # Prowlarr implementation name
          sync_level: fullSync # disabled | addOnly | fullSync
          fields:
            prowlarrUrl: http://prowlarr:9696
            baseUrl: http://sonarr:8989
            apiKey: !secret SONARR_API_KEY
            syncCategories: [5000, 5010, 5020, 5030, 5040]
          tags:
            - managed
      delete_unmanaged:
        enabled: false
        ignore:
          - "Manual App"
      sync_indexers: true # optional: run Prowlarr's "Sync App Indexers" command after syncing
  • Applications are matched by name + type (implementation)
  • fields are merged onto the Prowlarr schema for the implementation; keys are matched ignoring case and underscores, so snake_case and camelCase both work regardless of how the schema spells the field
  • Secrets shown by the server as ******** are left untouched unless you change them
  • sync_indexers: true triggers Prowlarr's global ApplicationIndexerSync command once per run

sync_profiles manages the profiles Prowlarr shows under Settings › Apps › Sync Profiles (its API calls them app profiles). Each entry takes a name plus the optional enable_rss, enable_automatic_search, enable_interactive_search and minimum_seeders:

config.yml
prowlarr:
  main:
    base_url: http://prowlarr:9696
    api_key: !secret PROWLARR_API_KEY

    sync_profiles:
      data:
        - name: Standard
          enable_rss: true
          enable_automatic_search: true
          enable_interactive_search: true
          minimum_seeders: 1
      delete_unmanaged:
        enabled: false
  • Profiles are matched by name, case-insensitively
  • A prop you leave out keeps its current value on the server, or takes Prowlarr's own default when the profile is created
  • Profiles are synced before indexers, so an indexer can reference one created in the same run

indexers entries are based on a schema definition (the Prowlarr definitionName, e.g. 1337x) and matched to the server by display name. Extra keys: enable, priority, sync_profile (the name must exist in Prowlarr or be listed under sync_profiles, otherwise the sync fails). On a new indexer without sync_profile the first profile on the server is used; on an update the existing profile is kept. indexer_proxies are matched by name + type (implementation: FlareSolverr, Http, Socks4, Socks5).

tags is a plain list of labels to ensure exist; delete_unmanaged_tags: { enabled, ignore } prunes server tags that are neither listed nor referenced by a managed resource. See Tags for the shared description of both blocks.

delete_unmanaged is off by default for every Prowlarr section and should stay that way unless your config is the full source of truth. See the warning under Experimental support.

Prowlarr download clients use the same download_clients block as the other *Arrs, minus the config and remote_paths sub-sections (Prowlarr has no equivalent endpoints).

Experimental supported fields​