Configuration Examples

Common configuration patterns for Recyclarr. Each section addresses a specific use case with complete, working examples.

• Add multiple quality profiles to one instance
• Customize template behavior
  • Override a custom format score
  • Add optional custom formats
  • Modify quality profile qualities
  • Disable quality profile syncing
  • Reset scores not in config
• Configure multiple arr instances
  • Single file with multiple instances
  • Separate files per instance
• File organization
  • Directory structure
  • Use secrets for sensitive values
• Consolidate existing config files
  • Before consolidation
  • After consolidation

Add multiple quality profiles to one instance

Use template includes to configure multiple TRaSH Guide profiles on a single Radarr or Sonarr instance. This is the recommended approach for most users.

radarr:
  movies:
    base_url: !secret radarr_url
    api_key: !secret radarr_apikey
    delete_old_custom_formats: true

    include:
      # Quality sizes (only needed once)
      - template: radarr-quality-definition-movie

      # HD Bluray + WEB (1080p)
      - template: radarr-quality-profile-hd-bluray-web
      - template: radarr-custom-formats-hd-bluray-web

      # UHD Bluray + WEB (4K)
      - template: radarr-quality-profile-uhd-bluray-web
      - template: radarr-custom-formats-uhd-bluray-web

      # Remux + WEB 1080p
      - template: radarr-quality-profile-remux-web-1080p
      - template: radarr-custom-formats-remux-web-1080p

      # Remux + WEB 2160p
      - template: radarr-quality-profile-remux-web-2160p
      - template: radarr-custom-formats-remux-web-2160p

Each quality profile requires two includes:

• quality-profile template creates the profile with its quality settings
• custom-formats template assigns CF scores to that profile

The quality-definition template only needs to be included once per instance.

tip

List available include templates with:

recyclarr config list templates --includes

Customize template behavior

Templates provide the full TRaSH Guide recommendation. Add a custom_formats section only when you need to modify the default behavior.

Override a custom format score

Change the score for specific custom formats while keeping the rest of the template defaults:

radarr:
  movies:
    base_url: !secret radarr_url
    api_key: !secret radarr_apikey

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

    custom_formats:
      - trash_ids:
          - b6832f586342ef70d9c128d40c07b872 # Bad Dual Groups
        assign_scores_to:
          - name: HD Bluray + WEB
            score: -10000  # More aggressive than template default

Your score takes precedence over the template. See the Include documentation for details on how scores merge.

Add optional custom formats

Templates include commented-out optional CFs. You can enable them by adding them to your config:

radarr:
  movies:
    base_url: !secret radarr_url
    api_key: !secret radarr_apikey

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

    custom_formats:
      # Movie Versions - prefer these releases
      - trash_ids:
          - 570bc9ebecd92723d2d21500f4be314c # Remaster
          - eca37840c13c6ef2dd0262b141a5482f # 4K Remaster
          - e0c07d59beb37348e975a930d5e50319 # Criterion Collection
          - eecf3a857724171f968a66cb5719e152 # IMAX
        assign_scores_to:
          - name: HD Bluray + WEB

Modify quality profile qualities

To add or change qualities in a profile, provide a complete qualities list. The list you provide replaces the template's qualities entirely:

sonarr:
  tv:
    base_url: !secret sonarr_url
    api_key: !secret sonarr_apikey

    include:
      - template: sonarr-quality-definition-series
      - template: sonarr-v4-quality-profile-web-1080p
      - template: sonarr-v4-custom-formats-web-1080p

    quality_profiles:
      - name: WEB-1080p
        qualities:
          - name: WEB 1080p
            qualities:
              - WEBDL-1080p
              - WEBRip-1080p
          - name: Bluray-1080p
          - name: Bluray-720p

You must include all qualities you want in the profile. See Quality Profile Qualities for why this uses replace behavior.

Disable quality profile syncing

To manage a quality profile manually in Sonarr/Radarr while still syncing custom formats:

radarr:
  movies:
    base_url: !secret radarr_url
    api_key: !secret radarr_apikey

    include:
      - template: radarr-quality-definition-movie
      # Quality profile template commented out - manage in Radarr UI
      # - template: radarr-quality-profile-hd-bluray-web
      - template: radarr-custom-formats-hd-bluray-web

Reset scores not in config

Use reset_unmatched_scores when you want Recyclarr to have exclusive control over CF scores in a profile:

radarr:
  movies:
    base_url: !secret radarr_url
    api_key: !secret radarr_apikey

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

    quality_profiles:
      - name: HD Bluray + WEB
        reset_unmatched_scores:
          enabled: true

With this enabled, any CF scores not set by your config or templates are reset to zero. This prevents stale scores from accumulating when you remove CFs from your config.

Configure multiple arr instances

Single file with multiple instances

Configure both Sonarr and Radarr (or multiple instances of either) in one file:

sonarr:
  tv-hd:
    base_url: !secret sonarr_url
    api_key: !secret sonarr_apikey

    include:
      - template: sonarr-quality-definition-series
      - template: sonarr-v4-quality-profile-web-1080p
      - template: sonarr-v4-custom-formats-web-1080p

radarr:
  movies-hd:
    base_url: !secret radarr_url
    api_key: !secret radarr_apikey

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

  movies-4k:
    base_url: !secret radarr_4k_url
    api_key: !secret radarr_4k_apikey

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

Run recyclarr sync to update all instances, or target specific services with recyclarr sync sonarr or recyclarr sync radarr.

Separate files per instance

For complex setups, use separate files in the configs/ directory:

config/
├── configs/
│   ├── sonarr.yml
│   ├── radarr-hd.yml
│   └── radarr-4k.yml
└── recyclarr.yml

Recyclarr automatically loads all YAML files in configs/. Each file uses the same structure as a single-file config. File names can be whatever you prefer.

File organization

Directory structure

A typical Recyclarr setup using Docker:

config/
├── recyclarr.yml          # Main config (auto-loaded)
├── secrets.yml            # API keys and URLs
├── configs/               # Additional configs (auto-loaded)
│   ├── sonarr.yml
│   └── radarr.yml
├── includes/              # Local include files (referenced, not auto-loaded)
│   └── my-custom-cfs.yml
├── cache/                 # Internal cache (managed by Recyclarr)
└── logs/                  # Application logs

Key points:

• recyclarr.yml and all files in configs/ are loaded automatically
• Files in includes/ are only loaded when referenced via include: - config:
• Each config file can contain any combination of Sonarr and Radarr instances

Use secrets for sensitive values

Store API keys and URLs in secrets.yml:

# secrets.yml
sonarr_url: http://sonarr:8989
sonarr_apikey: abc123

radarr_url: http://radarr:7878
radarr_apikey: def456

Reference them in your config:

radarr:
  movies:
    base_url: !secret radarr_url
    api_key: !secret radarr_apikey

See Value Substitution for details.

Consolidate existing config files

If you previously created multiple config files using recyclarr config create --template and want to combine them into a single file, follow this process.

info

For new setups, use template includes instead. This section is for cleaning up existing configurations.

Before consolidation

Two separate files created from templates:

hd-bluray-web.yml:

radarr:
  radarr-hd:
    base_url: !secret radarr_hd_url
    api_key: !secret radarr_hd_apikey

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

uhd-bluray-web.yml:

radarr:
  radarr-uhd:
    base_url: !secret radarr_uhd_url
    api_key: !secret radarr_uhd_apikey

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

After consolidation

If both files target the same Radarr instance, combine them:

radarr:
  movies:
    base_url: !secret radarr_url
    api_key: !secret radarr_apikey

    include:
      - template: radarr-quality-definition-movie

      # HD Bluray + WEB
      - template: radarr-quality-profile-hd-bluray-web
      - template: radarr-custom-formats-hd-bluray-web

      # UHD Bluray + WEB
      - template: radarr-quality-profile-uhd-bluray-web
      - template: radarr-custom-formats-uhd-bluray-web

The key insight: if both configs point to the same base_url, they should be one instance with multiple template includes, not two separate instance definitions.

If the files target different Radarr instances (different URLs), keep them as separate instance definitions in the same file or in separate files.