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
      - RECYCLARR_API_KEY=${RECYCLARR_API_KEY}
    volumes:
      - ./config:/config

The Recyclarr server does not start without its own API key, which must be at least 32 characters. This is separate from your Radarr API key. Create a .env file next to compose.yaml with a random key; Docker Compose reads it automatically:

echo "RECYCLARR_API_KEY=$(openssl rand -hex 32)" > .env

docker exec commands use the same key automatically. See API Key for other ways to store it.

Start the container in the background:

docker compose up -d

Recyclarr runs as a server that stays running. It takes a few seconds to start; wait until docker compose ps shows the container as healthy. The server has nothing to sync yet. You'll create its 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. Read the TRaSH Guides profile descriptions to pick one, then list the templates to find its ID:

docker exec recyclarr recyclarr config list templates

The list shows each template's ID next to its guide profile name. See Quick Setup Templates for how to preview a template before you use it.

Step 3: Create Your Configuration​

Create a config file from your chosen template. For example, to use the HD Bluray + WEB profile:

docker exec recyclarr recyclarr config create -t hd-bluray-web

This creates config/configs/hd-bluray-web.yml. Open it and 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: Run Your First Sync​

The server checks your configuration files once a minute and loads your new file on its own, without a restart. Follow its log until it shows Configuration changed and was reloaded, then press Ctrl+C:

docker compose logs -f recyclarr

If the log shows errors instead, fix them in your file and save it again. 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, the server loads your changes the same way. See Configuration Changes.

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. To see them for another profile, preview its template.

When the log shows Configuration changed and was reloaded, 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​