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 profile behavior
  • Override a custom format score
  • Add optional custom format groups
  • Modify quality profile qualities
  • Reset scores not in config
• Rename a guide-backed quality profile
• 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

Configure multiple TRaSH Guide profiles on a single Radarr or Sonarr instance using guide-backed quality profiles. 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

    quality_definition:
      type: movie

    quality_profiles:
      # HD Bluray + WEB (1080p)
      - trash_id: d1d67249d3890e49bc12e275d989a7e9  # HD Bluray + WEB
        reset_unmatched_scores:
          enabled: true

      # UHD Bluray + WEB (4K)
      - trash_id: 64fb5f9858489bdac2af690e27c8f42f  # UHD Bluray + WEB
        reset_unmatched_scores:
          enabled: true

      # Remux + WEB 1080p
      - trash_id: 9ca12ea80aa55ef916e3751f4b874151  # Remux + WEB 1080p
        reset_unmatched_scores:
          enabled: true

      # Remux + WEB 2160p
      - trash_id: fd161a61e3ab826d3a22d53f935696dd  # Remux + WEB 2160p
        reset_unmatched_scores:
          enabled: true

Each guide-backed profile pulls its quality profile settings, custom format scores, and quality definitions directly from the TRaSH Guides. A single trash_id reference replaces what previously required multiple include templates.

tip

Each template also includes commented-out custom_format_groups for optional CF groups (streaming services, movie versions, HDR options, etc.). The available groups differ per profile. See the Quick Setup Templates page for the full template contents.

Customize profile behavior

Guide-backed profiles provide the full TRaSH Guide recommendation. Add custom_formats or custom_format_groups sections 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 guide defaults:

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

    quality_definition:
      type: movie

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

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

Your score takes precedence over the guide-backed profile.

Add optional custom format groups

Templates include commented-out optional CF groups. Uncomment them to enable:

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

    quality_definition:
      type: movie

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

    custom_format_groups:
      add:
        - trash_id: f4f1474b963b24cf983455743aa9906c  # [Optional] Movie Versions

Modify quality profile qualities

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

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

    quality_definition:
      type: series

    quality_profiles:
      - trash_id: 72dae194fc92bf828f32cde7744e51a1  # WEB-1080p
        reset_unmatched_scores:
          enabled: true
        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.

Reset scores not in config

Use reset_unmatched_scores when you want Recyclarr to have exclusive control over CF scores in a profile. This is enabled by default in all official templates:

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

    quality_definition:
      type: movie

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

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

Rename a guide-backed quality profile

When syncing a guide-backed profile using trash_id, add name to use a custom name instead of the guide's default:

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

    quality_profiles:
      - trash_id: 9a0e43cb7a892e3e9c4f2f5c5e0dcf8e
        name: My Custom Profile Name

Recyclarr tracks the profile by trash_id, not by name. This means you can rename the profile at any time - update name in your config and Recyclarr renames the existing profile rather than creating a new one.

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

    quality_definition:
      type: series

    quality_profiles:
      - trash_id: 72dae194fc92bf828f32cde7744e51a1  # WEB-1080p
        reset_unmatched_scores:
          enabled: true

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

    quality_definition:
      type: movie

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

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

    quality_definition:
      type: movie

    quality_profiles:
      - trash_id: 64fb5f9858489bdac2af690e27c8f42f  # UHD Bluray + WEB
        reset_unmatched_scores:
          enabled: true

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
├── state/                 # Sync state (managed by Recyclarr)
├── resources/             # Git repos (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 config includes

• 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.

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

    quality_definition:
      type: movie

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

uhd-bluray-web.yml:

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

    quality_definition:
      type: movie

    quality_profiles:
      - trash_id: 64fb5f9858489bdac2af690e27c8f42f  # UHD Bluray + WEB
        reset_unmatched_scores:
          enabled: true

After consolidation

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

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

    quality_definition:
      type: movie

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

      - trash_id: 64fb5f9858489bdac2af690e27c8f42f  # UHD Bluray + WEB
        reset_unmatched_scores:
          enabled: true

The key insight: if both configs point to the same base_url, they should be one instance with multiple quality profiles, 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.