Version 8.0

Released February 20, 2026

Features have been removed or behavior changed. Most of the items here would have been deprecated in the past. Deprecations are always mentioned in release notes for feature releases.

Dedicated Includes Directory

The root directory for relative local include paths has changed. Previously, relative paths provided to the config include directive were rooted in ${appdatadir}/configs. Putting includes in the configs directory is no longer supported. Going forward, all includes should reside in ${appdatadir}/includes.

Migrating to the new directory is simple. Simply cut & paste any subdirectories containing include template YAML files to the new includes subdirectory. Assume you have the current structure:

.
├── configs/
│   ├── config1.yml
│   ├── config2.yml
│   └── local/
│       ├── my-include1.yml
│       └── my-include2.yml
└── includes/

An empty top-level includes will be created for you by Recyclarr. In the example above, we need to move the local directory to this top-level includes directory. The final structure should look like this:

.
├── configs/
│   ├── config1.yml
│   └── config2.yml
└── includes/
    └── local/
        ├── my-include1.yml
        └── my-include2.yml

By doing this, the relative paths in your templates section does not need to change:

include:
  - config: local/my-include1.yml
  - config: local/my-include2.yml

Recommended File Structure Changes (Optional)

If you followed the recommended file structure for your includes, then chances are you already have a configs/include directory. To avoid having the path look weird, such as includes/include/my-include1.yml, it is recommended that you remove the intermediate include directory or rename it. For example, you could change this:

include:
  - config: include/my-include1.yml
  - config: include/my-include2.yml

To:

include:
  - config: my-include1.yml
  - config: my-include2.yml

And have your filesystem change from:

.
├── configs/
│   ├── config1.yml
│   └── config2.yml
└── includes/
    └── include/
        ├── my-include1.yml
        └── my-include2.yml

To this:

.
├── configs/
│   ├── config1.yml
│   └── config2.yml
└── includes/
    ├── my-include1.yml
    └── my-include2.yml

YAML: Custom Formats `quality_profiles` Renamed

Prior to this major release, two quality_profiles nodes existed in YAML:

The top-level version, which defined quality profiles to sync
The one under custom_formats, which instructed Recyclarr which profile the CF scores should be synced to.

The fact that quality_profiles existed in two places with distinct meanings created a lot of confusion, especially in support channels. Starting with this major release, quality_profiles under custom_formats must be changed to assign_scores_to.

Before v8.0, if you had YAML like this:

radarr:
  movies:
    base_url: http://localhost:7878
    api_key: 123abc

    quality_profiles:
      - name: SD

    custom_formats:
      - trash_ids:
          - ed38b889b31be83fda192888e2286d83 # BR-DISK
          - 90cedc1fea7ea5d11298bebd3d1d3223 # EVO (no WEBDL)
        quality_profiles:
          - name: HD-1080p
          - name: HD-720p
            score: -1000
      - trash_ids:
          - 496f355514737f7d83bf7aa4d24f8169 # TrueHD ATMOS
          - 2f22d89048b01681dde8afe203bf2e95 # DTS X
        quality_profiles:
          - name: SD

You are required to change it to this:

radarr:
  movies:
    base_url: http://localhost:7878
    api_key: 123abc

    quality_profiles:
      - name: SD

    custom_formats:
      - trash_ids:
          - ed38b889b31be83fda192888e2286d83 # BR-DISK
          - 90cedc1fea7ea5d11298bebd3d1d3223 # EVO (no WEBDL)
        assign_scores_to: # <<< RENAMED
          - name: HD-1080p
          - name: HD-720p
            score: -1000
      - trash_ids:
          - 496f355514737f7d83bf7aa4d24f8169 # TrueHD ATMOS
          - 2f22d89048b01681dde8afe203bf2e95 # DTS X
        assign_scores_to: # <<< RENAMED
          - name: SD

Refer to the RENAMED comments in the above example for exact lines that changed.

Settings: Repository Configuration Replaced

The legacy repositories configuration format has been completely removed and replaced with the new resource_providers system. This change provides support for multiple repositories per content type, local directory support, and enables future extensibility.

Old Format (Removed)

repositories:
  trash_guides:
    clone_url: https://github.com/TRaSH-Guides/Guides.git
    branch: master
    sha1: c611e9df00bf9261bddfc749219295fe189ae552
  config_templates:
    clone_url: https://github.com/recyclarr/config-templates.git
    branch: master

New Format

resource_providers:
  - name: trash-guides
    type: trash-guides
    clone_url: https://github.com/TRaSH-Guides/Guides.git
    reference: c611e9df00bf9261bddfc749219295fe189ae552
    replace_default: true

  - name: config-templates
    type: config-templates
    clone_url: https://github.com/recyclarr/config-templates.git
    reference: master
    replace_default: true

Key Changes

Old	New
Nested structure (`trash_guides:`, `config_templates:`)	Flat list with explicit `type` property
`branch` and `sha1` properties	Unified `reference` property
Implicit replacement of official sources	Explicit `replace_default: true` required
Single repository per type	Multiple repositories per type supported
Git repositories only	Local directories also supported via `path`

Migration Notes

No repositories config? No changes needed - official sources are included automatically
Had custom repositories? Add type property and use replace_default: true if you want to replace official sources, or omit it to use your repository as a supplement
Using forks? Consider using supplemental providers instead of replacing official sources - this lets you get official updates while adding your customizations

See the Resource Providers documentation for complete configuration details.

YAML: `replace_existing_custom_formats` Removed

The replace_existing_custom_formats option has been removed. Custom format sync now uses ID-first matching: if a custom format is in the state, Recyclarr trusts that tracked ID regardless of name changes in the service.

Remove replace_existing_custom_formats from your configuration; it is no longer recognized. Recyclarr now automatically adopts existing custom formats that match by name during sync. No manual command is needed.

info

The state repair --adopt command previously recommended here was removed in v9.0. Sync handles adoption automatically.

CLI: `--debug` Option Removed

The -d|--debug option has been removed. Use --log debug instead.

Before:

recyclarr sync --debug

After:

recyclarr sync --log debug

The --log option enables log output mode and accepts three levels: debug, info (default), and warn. See the CLI Common Options documentation for details.

CLI: `list score-sets` Command

The --score-sets flag on list custom-formats has been replaced with a dedicated subcommand.

Before:

recyclarr list custom-formats radarr --score-sets

After:

recyclarr list score-sets radarr

CLI: List Command Output Format

List commands now display formatted tables instead of plain text. The global --raw option has been removed and is now specific to list commands, outputting TSV (tab-separated values) format for scripting.

Before (v7.x):

List of Custom Formats in the TRaSH Guides:

          - b124be9b146540f8e62f98fe32e49a2a # 1.0 Mono
          - 820b09bb9acbfde9c35c71e0e565dad8 # 1080p

After (v8.0):

List commands display formatted tables with category groupings and helpful instructions. Use --raw for machine-readable TSV output suitable for scripting.

Migration for Scripts

If you have scripts that parse list command output, update them to use --raw:

recyclarr list custom-formats radarr --raw

The --raw option outputs TSV format. Each list command documents its specific column format in the CLI reference.

Config Templates Changes

Version-Aware Branch Selection

Config-templates providers now use version-aware branch selection. Recyclarr automatically selects the v{major} branch matching your version (e.g., v8 for Recyclarr 8.x), falling back to master/main if unavailable. This ensures template compatibility with your Recyclarr version.

No user action is required. If you have an explicit reference in your settings, it continues to override auto-detection.

v7 Templates Maintenance Policy

With the introduction of version-aware branches, v7 templates (the master branch) are now in maintenance mode:

No new features: v7 templates will not receive updates for new guide changes
Critical fixes only: Only severe issues will be addressed on the v7 branch
Template drift expected: v7 templates may diverge from current TRaSH Guides recommendations

If you're experiencing template drift from the guides: The recommended path is upgrading to Recyclarr v8, which uses the v8 branch with actively maintained templates.

v8 templates are being simplified to leverage guide-backed quality profiles and custom format groups, providing better alignment with the TRaSH Guides while reducing configuration complexity.

Official Include Templates Removed

All official include templates have been removed from the v8 config-templates branch. If your configuration uses include: - template: directives referencing official include templates (such as radarr-custom-formats-hd-bluray-web or radarr-quality-profile-hd-bluray-web), those references will no longer resolve.

The old include templates were static lists of trash IDs for custom formats and quality profiles. This approach has been replaced by guide-backed quality profiles and custom format groups, which reference TRaSH Guides content dynamically instead of hardcoding individual trash IDs.

Before (v7):

radarr:
  movies:
    base_url: http://localhost:7878
    api_key: your_api_key

    include:
      - template: radarr-custom-formats-hd-bluray-web
      - template: radarr-quality-profile-hd-bluray-web
      - template: radarr-quality-definition-movie

After (v8):

radarr:
  movies:
    base_url: http://localhost:7878
    api_key: your_api_key

    quality_definition:
      type: movie

    quality_profiles:
      - trash_id: d1d67249d3890e49bc12e275d989a7e9  # HD Bluray + WEB
        reset_unmatched_scores:
          enabled: true

Guide-backed profiles pull their quality profile settings and custom format scores directly from the TRaSH Guides, so you no longer need separate includes for custom formats, quality profiles, and quality definitions. A single trash_id reference replaces what previously required multiple include templates.

info

Local file includes (include: - config: my-include.yml) are unaffected by this change. Only official include templates from the config-templates repository have been removed.

Adopting Guide-Backed Quality Profiles

If you have existing quality profiles in Sonarr or Radarr that were created by Recyclarr v7 (or manually), you cannot simply add a trash_id to your config and expect Recyclarr to update the existing profile. Without the adoption step below, Recyclarr treats the trash_id as a new profile and creates a duplicate.

warning

Skipping these steps will result in duplicate profiles in your service. Follow them in order for each profile you want to convert to guide-backed.

Adoption Steps

Strip your quality profile config down to just name (and reset_unmatched_scores, if you use it). The name must match what the profile is currently called in Sonarr/Radarr. Remove all other properties temporarily.
Add the trash_id for the corresponding guide profile. See the name reference table below to find the correct trash_id.
Run recyclarr sync. Recyclarr automatically adopts the existing profile and recognizes it as the guide-backed profile going forward.
You can now remove name to let the guide name take effect (which renames the profile on the next sync), or set name to any custom value you prefer. You can also restore other properties if you want to override the guide-provided values.

Before (v7):

radarr:
  movies:
    base_url: http://localhost:7878
    api_key: your_api_key

    quality_profiles:
      - name: HD Bluray + WEB (GER)
        score_set: german
        reset_unmatched_scores:
          enabled: true
        upgrade:
          allowed: true
          until_quality: Merged QPs
          until_score: 35000
        min_format_score: 0
        quality_sort: top
        qualities:
          - name: Merged QPs
            qualities:
              - Bluray-1080p
              - WEBRip-1080p
              - WEBDL-1080p
              - Bluray-720p
              - WEBDL-720p
              - WEBRip-720p

After step 2 (ready for adoption):

radarr:
  movies:
    base_url: http://localhost:7878
    api_key: your_api_key

    quality_profiles:
      - trash_id: 2b90e905c99490edc7c7a5787443748b  # [German] HD Bluray + WEB  # <<< NEW
        name: HD Bluray + WEB (GER)
        reset_unmatched_scores:
          enabled: true

After running recyclarr sync (step 3), the profile is adopted. You can then remove name to let the guide name take over, or keep it to preserve your current name.

tip

If you want to keep your current profile name as-is, leave the name property set to your existing name after step 3. Recyclarr will continue using that name instead of the guide default.

Guide Profile Name Reference

TRaSH Guides standardized quality profile names to use a [Prefix] convention. The tables below show the old names from v7 config templates alongside the new guide names and their trash_id values. Use this to find the correct trash_id for your existing profile and to know what the profile will be renamed to if you remove the name override.

Anime

Old Name	Guide Name	Service	`trash_id`
Remux-1080p - Anime	[Anime] Remux-1080p	Sonarr	`20e0fc959f1f1704bed501f23bdae76f`
Remux-1080p - Anime	[Anime] Remux-1080p	Radarr	`722b624f9af1e492284c4bc842153a38`

German

Old Name	Guide Name	Service	`trash_id`
HD Bluray + WEB (GER)	[German] HD Bluray + WEB	Sonarr	`dca7e5e9e99c703bcbdaaa471dd40e98`
HD Bluray + WEB (GER)	[German] HD Bluray + WEB	Radarr	`2b90e905c99490edc7c7a5787443748b`
HD Remux + WEB (GER)	[German] HD Remux + WEB	Sonarr	`0dd5f085ed61a1e01f6d347779dfa1bc`
HD Remux + WEB (GER)	[German] HD Remux + WEB	Radarr	`c13c33fdd2c306266b34cb9946de5919`
UHD Bluray + WEB (GER)	[German] UHD Bluray + WEB	Sonarr	`3b0fa37fddaaefc931b75f2889d4b4f5`
UHD Bluray + WEB (GER)	[German] UHD Bluray + WEB	Radarr	`27cc3d153c0a799fd139ef1ff4c4cc42`
UHD Bluray + WEB (GER) (Alt.)	[German] UHD Bluray + WEB (Alternative)	Sonarr	`7324309a7d1e10dc0dc2cea6c70ed852`
UHD Bluray + WEB (GER) (Alt.)	[German] UHD Bluray + WEB (Alternative)	Radarr	`425da1ba30711b55d2eb371437ec98d7`
UHD Remux + WEB (GER)	[German] UHD Remux + WEB	Sonarr	`08cececf1840290f6fd490b7d79e8642`
Remux + WEB 2160p (GER)	[German] Remux + WEB 2160p	Radarr	`79faa9943cef2f510b997b1f2a9f3ea6`

French MULTi.VO

Old Name	Guide Name	Service	`trash_id`
FR-MULTi-VO-WEB-1080p	[French MULTi.VO] HD Bluray + WEB (1080p)	Sonarr	`4c48f506c1116a3a57ae33f12346bd15`
FR-MULTi-VO-WEB-2160p	[French MULTi.VO] UHD Bluray + WEB (2160p)	Sonarr	`6fa7364373e8f06206871d9c20a4fb3e`
FR-MULTi-VO-HD	[French MULTi.VO] HD Bluray + WEB	Radarr	`2572ce3ea4eef1c19d59e0e20ed1cea7`
FR-REMUX-MULTi-VO-HD	[French MULTi.VO] HD Remux (1080p)	Radarr	`c6460a102b312200c095a2d0982e0461`
FR-MULTi-VO-UHD	[French MULTi.VO] UHD Bluray + WEB	Radarr	`92ead7022d13a7858d54e328e6a2f8f9`
FR-REMUX-MULTi-VO-UHD	[French MULTi.VO] UHD Remux (2160p)	Radarr	`1fef28c8c919f31cd86283b1baf527d4`

Environment: `RECYCLARR_APP_DATA` Removed

The RECYCLARR_APP_DATA environment variable has been removed. If it is set, Recyclarr exits with the following error:

RECYCLARR_APP_DATA is no longer supported. Use these instead:
  - RECYCLARR_CONFIG_DIR: User configuration (replaces APP_DATA)
  - RECYCLARR_DATA_DIR: Ephemeral data (optional, defaults to CONFIG_DIR)

To migrate, rename RECYCLARR_APP_DATA to RECYCLARR_CONFIG_DIR in your
environment.

Migration

Rename RECYCLARR_APP_DATA to RECYCLARR_CONFIG_DIR in your environment, shell profile, Docker Compose file, or systemd unit.

Before:

export RECYCLARR_APP_DATA="/path/to/appdata"

After:

export RECYCLARR_CONFIG_DIR="/path/to/appdata"

Optionally, set RECYCLARR_DATA_DIR to a separate path if you want to keep ephemeral files (resources, logs) out of your backup. If unset, data files remain in the config directory as before.

See the Environment Variables reference for full details.

CLI: `--app-data` Option Removed

The --app-data CLI option has been removed. Use the RECYCLARR_CONFIG_DIR environment variable instead.

Dedicated Includes Directory​

Recommended File Structure Changes (Optional)​

YAML: Custom Formats quality_profiles Renamed​

Settings: Repository Configuration Replaced​

Old Format (Removed)​

New Format​

Key Changes​

Migration Notes​

YAML: replace_existing_custom_formats Removed​

CLI: --debug Option Removed​

CLI: list score-sets Command​

CLI: List Command Output Format​

Migration for Scripts​

Config Templates Changes​

Version-Aware Branch Selection​

v7 Templates Maintenance Policy​

Official Include Templates Removed​

Adopting Guide-Backed Quality Profiles​

Adoption Steps​

Guide Profile Name Reference​

Anime​

German​

French MULTi.VO​

Environment: RECYCLARR_APP_DATA Removed​

Migration​

CLI: --app-data Option Removed​

Dedicated Includes Directory

Recommended File Structure Changes (Optional)

YAML: Custom Formats `quality_profiles` Renamed

Settings: Repository Configuration Replaced

Old Format (Removed)

New Format

Key Changes

Migration Notes

YAML: `replace_existing_custom_formats` Removed

CLI: `--debug` Option Removed

CLI: `list score-sets` Command

CLI: List Command Output Format

Migration for Scripts

Config Templates Changes

Version-Aware Branch Selection

v7 Templates Maintenance Policy

Official Include Templates Removed

Adopting Guide-Backed Quality Profiles

Adoption Steps

Guide Profile Name Reference

Anime

German

French MULTi.VO

Environment: `RECYCLARR_APP_DATA` Removed

Migration

CLI: `--app-data` Option Removed