Recyclarr: Automate Your Media Server Configuration
Recyclarr reads a single YAML file and pushes recommended settings from TRaSH Guides straight into your Sonarr and Radarr instances. No more manual configuration drift.
sonarr:
instance-one:
base_url: http://sonarr:8989
api_key: your-api-key
quality_profiles:
- name: HD Bluray + WEB
trash_id: ed38b229b70db0a9877336d6a05873c8
upgrade: allowed
score_set: anime-radarr
radarr:
movie-instance:
base_url: http://radarr:7878
api_key: your-api-key
custom_formats:
- trash_ids:
- e0c07d59beb6037209912b65d2cd570f
- 90a6f9dc2854a62407502f9bddaca160
What is Recyclarr?
Recyclarr is an open-source command-line application designed to eliminate the manual effort involved in configuring Sonarr and Radarr. Instead of clicking through dozens of settings panels, manually entering custom format scores, and painstakingly building quality profiles, you write a declarative YAML file describing your desired setup. Recyclarr takes that file, fetches the latest recommendations from the TRaSH Guides, and applies everything to your instances automatically.
Whether you are setting up a fresh media server or maintaining an existing one, Recyclarr ensures your configuration stays perfectly aligned with community best practices — without requiring constant manual oversight. The entire philosophy is simple: describe what you want once, and let the tool handle the rest.
YAML-Driven
A single declarative configuration file defines every aspect of your Sonarr and Radarr setup. No GUI clicks, no spreadsheets to maintain.
TRaSH Guides Integration
Directly pulls recommended custom formats, quality profiles, and scores from the most trusted community resource for arr configuration.
Reconciling Sync
Every run compares your current instance state against the YAML definition and makes only the necessary changes to bring them in line.
Manual Configuration Is Broken
Anyone who has set up Sonarr or Radarr knows the pain. Here is what most users deal with before discovering Recyclarr.
Hours of Repetitive Clicking
Setting up custom formats alone can take hours. Each format needs to be found, imported, scored, and assigned to the correct quality profile. Multiply that across Sonarr and Radarr, and an afternoon disappears. Every new instance means starting over.
Configuration Drift Over Time
The TRaSH Guides are continuously updated with new custom formats, adjusted scores, and revised quality profiles. If you configured everything manually months ago, your setup is already outdated — and you likely do not even know which parts have fallen behind.
No Reproducibility
When you set up everything through a web UI, there is no record of what you did or why. If you need to migrate servers, recreate an instance, or debug a quality issue, you are left guessing. Manual setups are inherently fragile and impossible to version-control.
How Recyclarr Works
Four simple steps stand between you and a perfectly configured media server. Here is the exact workflow that Recyclarr follows each time you run a sync.
Install Recyclarr
Download the binary for your platform, install via Docker, or build from source. The CLI is lightweight with zero external dependencies beyond a .NET runtime.
Write Your YAML
Create a recyclarr.yml file specifying your Sonarr and Radarr instances, API keys, desired quality profiles, and which TRaSH Guide configurations to apply.
Run the Sync
Execute a single command. Recyclarr fetches guide data, compares it against your instances, and pushes all necessary changes — creating, updating, or removing resources as needed.
Schedule & Forget
Set up a cron job or Docker restart policy to run Recyclarr periodically. Each sync reconciles your instances back to the YAML definition, catching any guide updates automatically.
Built for Serious Media Setups
Recyclarr is not a toy script. It is a robust tool designed around real-world configuration management principles, tailored specifically for the arr ecosystem.
Name: HD Bluray + WEB
Items: 14
Upgrade: Allowed
Min Score: 1000
Cutoff: 10000
Complete Profile Management
Recyclarr creates and updates quality profiles with all the correct items, cutoffs, upgrade rules, and minimum scores defined by the TRaSH Guides. Instead of manually adding each quality level and sorting them, you reference a guide profile by its trash ID and Recyclarr handles the entire structure. If the guide updates a profile, your next sync picks up the changes automatically.
- Auto-create and update quality profiles
- Correct item ordering and grouping
- Upgrade allowed/disallowed enforcement
- Minimum score and cutoff syncing
HDR: dv-hdr10plus +2500
Audio: truehd-atmos +1500
Codec: x265 -10000
Release: scene -9999
Custom Format Automation
Custom formats are the backbone of a well-tuned arr setup, but managing them manually is tedious. Recyclarr pulls the exact custom format definitions from the TRaSH Guides — including conditions, exclusions, and scores — and creates or updates them in your instances. You simply list the trash IDs you want, and Recyclarr does the rest.
- Bulk import by trash ID
- Automatic score assignment
- Diff-based updates (only changes what differs)
- Remove formats not in your YAML
Port: 8989
SSL: false
Branch: main
Tags: [anime, movies]
Multi-Instance Support
Most serious media setups run multiple Sonarr or Radarr instances — one for anime, another for regular TV, separate ones for 4K content. Recyclarr handles this natively. Each instance gets its own block in the YAML with its own URL, API key, and configuration. A single sync command iterates through all of them.
- Unlimited instances per service
- Independent profiles per instance
- Shared or unique custom formats
- Per-instance score overrides
One YAML to Rule Them All
The entire power of Recyclarr comes down to a single configuration file. This file lives in your repository, can be version-controlled, shared with friends, or used to spin up identical setups on new servers.
Every aspect of your Sonarr and Radarr configuration — instances, quality profiles, custom formats, scores, and exclusions — is declared in one place. There are no hidden settings, no GUI state to lose, and no "I forgot how I set this up" moments.
- Version control your entire media server config
- Share configurations with the community
- Reproduce setups across multiple servers
- Easy backup and disaster recovery
base_url_template: http://{instance}.local:{port}
sonarr:
tv-4k:
base_url: http://sonarr-4k:8989
api_key: ${SONARR_4K_KEY}
quality_profiles:
- name: 4K HDR
trash_id: dcbb2d2cc0a1b7538578b8f5d0a0b6b8
upgrade: allowed
score_set: tv-4k
radarr:
movies:
base_url: http://radarr:7878
api_key: ${RADARR_KEY}
quality_profiles:
- name: HD Bluray + WEB
trash_id: ed38b229b70db0a9877336d6a05873c8
TRaSH Guides Integration Flow
Recyclarr acts as the bridge between your YAML configuration and the TRaSH Guides repository. Here is how data flows from guide to your instances.
Your YAML
Define instances, profiles, and trash IDs
Recyclarr CLI
Reads YAML and fetches guide data
TRaSH Guides
Community-maintained format definitions
Sonarr / Radarr
Profiles and formats applied via API
Sonarr & Radarr — Fully Covered
Recyclarr provides deep, first-class support for both major media management services in the arr ecosystem.
Sonarr TV Shows
Complete quality profile and custom format management for your television show library, including anime-specific configurations.
- Quality profile creation and sync
- Custom format import with scores
- Anime-specific score sets
- Multi-instance support (anime, regular, 4K)
- Release profile management
Radarr Movies
Full feature parity for movie management, including separate score sets for different quality tiers and release type preferences.
- Quality profile creation and sync
- Custom format import with scores
- Movie-specific score sets
- Multi-instance support (regular, 4K, remux)
- Release profile management
What Happens During a Sync
Every time you run Recyclarr, it follows a precise sequence of operations to ensure your instances match your YAML exactly.
Fetch Guide Data
Recyclarr reaches out to the TRaSH Guides GitHub repository and downloads the latest quality definition files, custom format templates, and score sets referenced in your YAML.
Compare Current State
Using the Sonarr/Radarr API, Recyclarr reads your current instance configuration — existing quality profiles, custom formats, and their current settings — and builds a diff against the guide definitions.
Apply Changes
Only the differences are pushed to your instances. New profiles are created, existing ones are updated field-by-field, and orphaned formats are optionally removed. Nothing is touched if it already matches.
Report Results
Recyclarr outputs a detailed summary showing exactly what was created, updated, or skipped. You always know what changed and what stayed the same, making it easy to audit each sync run.
Format Categories Recyclarr Manages
Hover over each card to see what Recyclarr handles for that format category.
HDR Formats
DV, HDR10, HDR10+, PQ
HDR Detection
Recyclarr imports all HDR-related custom formats with correct scores for Dolby Vision, HDR10, HDR10+, and PQ/HLG variants. Ensures your setup prefers the best HDR format available.
Audio Formats
Atmos, TrueHD, DTS-X, FLAC
Audio Scoring
Imports audio codec formats with scores that prioritize lossless audio like TrueHD Atmos and DTS-X over lossy alternatives. Configurable per quality profile for different tier setups.
Video Codecs
x264, x265, AV1, MPEG-2
Codec Filtering
Penalizes undesirable codecs like x265 in 1080p releases or MPEG-2 encodes. Ensures your library only accepts properly encoded media for each quality tier.
Release Types
WEB-DL, Bluray, Remux, HDTV
Release Preference
Manages release source formats to prefer WEB-DL over HDTV, Bluray over WEB for archival, and Remux for lossless storage. Score sets adapt based on your quality profile tier.
Benefits That Actually Matter
These are not theoretical advantages. Every benefit below directly translates to time saved, fewer errors, and a more reliable media server.
Save Hours on Every Setup
What used to take 3-4 hours of manual clicking through Sonarr and Radarr web UIs now takes a single command. Your first sync creates everything from scratch. Subsequent syncs take seconds. If you manage multiple instances, the time savings multiply dramatically. Users report going from an entire afternoon of setup to under five minutes.
Eliminate Human Error
No more typos in custom format conditions, no forgotten score assignments, no mismatched quality profile items. The YAML is your single source of truth.
Stay Automatically Updated
When TRaSH Guides adds a new custom format or adjusts scores, your next scheduled sync picks up the changes without any manual intervention.
Version-Control Everything
Your YAML file lives in Git. Every change to your media server configuration is tracked, reversible, and auditable. Roll back to any previous state with a single git checkout.
Disaster Recovery
Servers crash, Docker containers get recreated, migrations happen. With Recyclarr, recovering your full configuration is one sync away from a fresh instance.
Recyclarr vs Manual Configuration
A feature-by-feature look at why Recyclarr is the clear choice for anyone serious about their media server setup.
Pros & Cons of Recyclarr
Every tool has trade-offs. Here is an honest look at where Recyclarr excels and where you might need to work around its limitations.
Pros
- Eliminates hours of manual GUI configuration for Sonarr and Radarr
- Keeps your setup automatically in sync with TRaSH Guide recommendations
- YAML configuration is version-controllable, shareable, and auditable
- Idempotent — safe to run repeatedly without side effects
- Active open-source community with regular updates and improvements
- Works great with Docker and scheduled tasks for hands-off operation
Cons
- Requires basic YAML knowledge — not ideal for complete non-technical users
- Depends on TRaSH Guide trash IDs — if a guide changes IDs, configs may break
- CLI-only tool — no web interface or GUI for visual configuration
- Only supports Sonarr and Radarr — no Lidarr, Readarr, or Prowlarr integration
- Advanced customizations beyond guide defaults still require manual work
What Users Are Saying
Real feedback from the media server community about their experience with Recyclarr.
I spent an entire Saturday setting up custom formats in Radarr manually. Found Recyclarr the next week. Now I can reproduce that entire setup in about 30 seconds. I wish I had known about this sooner.
The best part isn't even the initial setup — it's knowing that when TRaSH Guides adds a new custom format or changes a score, my weekly cron job just picks it up. Zero maintenance overhead.
I manage Sonarr instances for 5 family members. Before Recyclarr, keeping them all consistent was a nightmare. Now I just maintain one YAML repo and sync to all instances. Game changer.
Frequently Asked Questions
Common questions about Recyclarr, answered clearly and concisely.
Recyclarr represents the exact kind of infrastructure-as-code thinking that the homelab community needs. Treating your media server configuration the same way you treat server infrastructure — declarative, version-controlled, reproducible — is the right approach. Every serious media server admin should be using this.
The moment I put my Recyclarr YAML in a Git repo, I felt a weight lift off my shoulders. No more wondering if my three Sonarr instances are configured the same way. No more manual notes about which custom formats I added. It's all right there in the file, and one command makes reality match the declaration.
Ready to Automate Your Setup?
Stop wasting time on manual configuration. Download Recyclarr, write your YAML, and let the tool handle the rest. Your future self will thank you.
Free and open source under the MIT License. No account required.