Skip to main content

The documentation here is for an unreleased version of Recyclarr.

Visit the documentation site for the Current Version instead.

Getting Started

This guide walks you through setting up Recyclarr to sync TRaSH Guide quality profiles to Radarr. By the end, you'll have a working quality profile with custom formats and proper media naming. No YAML expertise required.

Prerequisites​

  • Radarr is running and accessible (Sonarr setup is similar — just use sonarr templates)
  • You know where to find your API key (Settings → General → Security)

Step 1: Install Recyclarr​

Add the Recyclarr service to your existing Compose file (compose.yaml or docker-compose.yml), or create a new compose.yaml:

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr:9
    container_name: recyclarr
    user: 1000:1000
    restart: unless-stopped
    environment:
      - TZ=America/New_York
    volumes:
      - ./config:/config

Don't start the container yet. Recyclarr runs as a server that stays running, and it reads your configuration when it starts. You'll create that configuration in the next steps.

For networking, tags, and native installs, see the Installation Guide.

Step 2: Choose a Quality Profile​

Recyclarr provides ready-to-use templates that match TRaSH Guide quality profiles. Browse them on the Quick Setup Templates page. Each matches a TRaSH Guides profile.

Step 3: Create Your Configuration​

Create a config file from your chosen template. For example, to use the HD Bluray + WEB profile, copy the contents of the HD Bluray + WEB template into a new file at config/configs/hd-bluray-web.yml. Then update base_url and api_key:

radarr:
  hd-bluray-web:
    base_url: http://radarr:7878  # Your Radarr URL
    api_key: your_api_key_here    # Radarr → Settings → General → API Key

Optionally, add this line if you want Recyclarr to delete custom formats it previously synced but are no longer in your configuration:

    delete_old_custom_formats: true

That's it. The template already includes the quality definition, quality profile, and custom formats from the TRaSH Guide.

Step 4: Start Recyclarr and Sync​

Start the container in the background:

docker compose up -d

The server takes a few seconds to start. Wait until docker compose ps shows the container as healthy. Recyclarr now syncs automatically once a day. To run your first sync right away:

docker exec recyclarr recyclarr sync

When you edit your configuration later, restart the container so Recyclarr reads the changes. Wait until it is healthy again before you run recyclarr commands:

docker compose restart recyclarr

Step 5: Verify the Sync​

Check these locations in the service to confirm the sync worked:

  • Settings → Profiles — Your new quality profile appears ("HD Bluray + WEB")
  • Settings → Custom Formats — New custom formats with scores assigned
  • Settings → Quality — Size ranges updated for each quality level

Adding More Profiles​

Want multiple quality profiles (e.g., both 1080p and 4K)? Add more guide-backed profiles to your existing config file.

Edit your hd-bluray-web.yml (or create a new config file) and add additional trash_id entries under quality_profiles. Here's an example with four profiles:

radarr:
  main:
    base_url: http://radarr:7878
    api_key: your_api_key_here
    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 and custom format scores directly from the TRaSH Guides, so a single trash_id is all you need per profile.

tip

Each template also includes commented-out custom_format_groups for optional CF groups like streaming services and movie versions. See the Quick Setup Templates page for the full template contents.

Restart the container:

docker compose restart recyclarr

When docker compose ps shows the container as healthy, sync again to create all profiles:

docker exec recyclarr recyclarr sync

Adding Media Naming​

To sync TRaSH Guide naming formats, first see what's available:

docker exec recyclarr recyclarr list naming radarr

Then add a media_naming section to your config:

radarr:
  main:
    base_url: http://radarr:7878
    api_key: your_api_key_here

    quality_definition:
      type: movie

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

    # Results visible in: Radarr → Settings → Media Management
    media_naming:
      folder: plex-tmdb
      movie:
        rename: true
        standard: plex-tmdb

When to Customize​

The templates provide the full TRaSH Guide recommendation. For most users, that's everything you need.

You only need a custom_formats: section if you want to:

  • Override a score — Change the default score for a specific custom format
  • Add optional custom formats — Include CFs marked as "optional" in the TRaSH Guides

For customization examples, see the Configuration Examples page.

Next Steps​