Forty Custom Formats Walk Into Sonarr
You read the TRaSH Guides. You opened Sonarr, clicked Settings, Custom Formats, and started pasting JSON. Forty entries later you built a quality profile, typed a score next to each one, and went to bed proud. Three weeks after that, TRaSH changed a score, added a release group to the “LQ” list, and your setup quietly turned into a snapshot of a guide that no longer exists.
Recyclarr fixes that. It reads your YAML file, pulls the current TRaSH Guides data, and makes Sonarr and Radarr match it: custom formats, quality profiles, scores, quality sizes, and naming. You describe the outcome once, and a daily job keeps it true. That is the combo: TRaSH Guides decides what good looks like, Recyclarr does the typing.
Full example: Clone the working files at github.com/KingPin/sumguy-examples/self-hosting/recyclarr-trash-guides-sonarr-radarr
Everything below targets Recyclarr v8 (v8.8.1 today). The config format changed a lot between major versions, so a tutorial that lists every custom format by hand and stacks include templates describes an older tool with the same name.
What Each Piece Does
TRaSH Guides is a community-maintained set of recommendations for Sonarr and Radarr. Each custom format (CF) is a JSON file with a trash_id, a name, and the matching rules. Each quality profile is another JSON file that lists the qualities, the CFs, and the score for each CF. The guides also publish quality sizes (min, max, preferred MB per minute) and naming formats.
Recyclarr is a command-line tool that reads those JSON files and talks to the Sonarr and Radarr APIs. It creates or updates what the guide says, and only what your config asks for.
In v8 the config got much shorter. You point at a guide-backed quality profile with one trash_id, and Recyclarr pulls the qualities, the custom formats, the scores, and (on Radarr) the language setting from the guide. Older configs spelled all of that out by hand.
A forklift is a good picture here. TRaSH Guides is the warehouse manifest. Recyclarr is the forklift. You can still carry every pallet yourself, but your back will have opinions.
Step 1: Run It in Docker
Recyclarr ships as ghcr.io/recyclarr/recyclarr (and recyclarr/recyclarr on Docker Hub). Use the major version tag, :8. There is no latest tag, on purpose, so a major release cannot change your setup while you sleep.
# Recyclarr in cron mode. Sonarr and Radarr already run on the external# network below. Create it once with: docker network create medianetworks: media: external: true
services: recyclarr: image: ghcr.io/recyclarr/recyclarr:8 container_name: recyclarr user: 1000:1000 restart: unless-stopped networks: [media] env_file: .env environment: - TZ=UTC - CRON_SCHEDULE=0 4 * * * volumes: - ./config:/configThree details matter here:
- The container runs rootless.
PUIDandPGIDdo nothing. Setuser:instead, and make sure that user can write to./config. CRON_SCHEDULEdefaults to@daily. The line above moves it to 04:00. With no command on the container, it sits idle and runssyncon that schedule.- Recyclarr must reach Sonarr and Radarr by name. A shared Docker network is the simplest way, and it skips your reverse proxy entirely.
The API keys go in a .env file next to the compose file:
SONARR_URL=http://sonarr:8989SONARR_API_KEY=YOUR_SONARR_API_KEYRADARR_URL=http://radarr:7878RADARR_API_KEY=YOUR_RADARR_API_KEYFind each key under Settings, General, Security in the app. Keep .env out of git.
Step 2: Write a Config That Fits on a Screen
Recyclarr reads /config/recyclarr.yml (plus any .yml files in /config/configs/). Each top-level key is a service, and each name under it is an instance you pick. The !env_var tag pulls a value from the container environment, so the keys never land in the YAML.
# yaml-language-server: $schema=https://schemas.recyclarr.dev/v8/config-schema.jsonsonarr: series: base_url: !env_var SONARR_URL api_key: !env_var SONARR_API_KEY delete_old_custom_formats: true
quality_definition: type: series
quality_profiles: - trash_id: 72dae194fc92bf828f32cde7744e51a1 # WEB-1080p reset_unmatched_scores: enabled: true
# Override: allow x265 (HD) releases. The guide default is -10000. custom_formats: - trash_ids: - 47435ece6b99a0b477caf360e79ba0bb # x265 (HD) assign_scores_to: - trash_id: 72dae194fc92bf828f32cde7744e51a1 # WEB-1080p score: 0
media_naming: series: default season: default episodes: rename: true standard: default
radarr: movies: base_url: !env_var RADARR_URL api_key: !env_var RADARR_API_KEY delete_old_custom_formats: true
quality_definition: type: movie
quality_profiles: - trash_id: 9ca12ea80aa55ef916e3751f4b874151 # Remux + WEB 1080p reset_unmatched_scores: enabled: true
media_naming: folder: default movie: rename: true standard: standardThat is the whole config for two apps. The first line points your editor at the JSON schema, so a typo in a key shows up before the sync does.
If you prefer a secrets.yml file in the config directory, use !secret sonarr_apikey in place of !env_var. A missing secret key or an unset variable with no default stops Recyclarr from loading the config at all, which is the behavior you want.
Where the trash_ids come from
Never copy a trash_id from a forum post. Ask Recyclarr:
docker compose run --rm recyclarr list quality-profiles sonarrdocker compose run --rm recyclarr list quality-profiles radarrdocker compose run --rm recyclarr list custom-formats radarrdocker compose run --rm recyclarr list custom-format-groups radarrThese print the guide’s own IDs, names, and links. The two profile IDs above are the ones for Sonarr “WEB-1080p” and Radarr “Remux + WEB 1080p”. Pick the profile that matches your storage and your patience.
Want a starter file instead? config list templates shows the official templates, and config create --template web-1080p writes one into configs/. The templates fill in base_url with a placeholder, so edit that before you sync.
docker compose run --rm recyclarr config list templatesdocker compose run --rm recyclarr config create --template web-1080pOne v8 change catches people: the official templates no longer ship include fragments. The include key still works, but only with config: (your own YAML file) or with a custom resource provider. If an old tutorial tells you to add an include template for a quality profile, skip that step. A trash_id does that job now.
Step 3: Preview, Then Sync
Always preview first. The --preview flag does every read the real sync does and none of the writes.
docker compose run --rm recyclarr sync --previewThe output is a set of tables per instance: custom formats to create, profiles to create or change, quality sizes to update. On a fresh Sonarr, expect a long list of creates. On the second run, expect almost nothing, and that quiet is the point.
When the preview looks right, run it for real:
docker compose run --rm recyclarr syncYou can limit a run to one service or one instance:
docker compose run --rm recyclarr sync sonarrdocker compose run --rm recyclarr sync -i movies --previewThen open Sonarr, go to Settings, Profiles, and check that “WEB-1080p” exists with its scores. Then start the long-running container so the schedule takes over:
docker compose up -dSync runs as independent stages: custom formats, quality profiles, quality sizes, naming, and media management (not used in this config). On Sonarr v5 the profile stage syncs the sizes. Profiles depend on the custom formats, so a failure in the first one skips the second. The sizes and naming stages keep going. A diagnostics panel at the end of the output tells you which stage failed and why.
Overriding a Score
The guide is a good default, not a commandment. The override in the config above is the usual case: the Golden Rule says x265 releases of HD content get a score of -10000 (effectively banned), and you run a box that handles HEVC fine.
Use custom_formats with assign_scores_to. Point at the profile by trash_id (or by name), and set the score. Your score wins over the guide’s.
custom_formats: - trash_ids: - 47435ece6b99a0b477caf360e79ba0bb # x265 (HD) assign_scores_to: - trash_id: 72dae194fc92bf828f32cde7744e51a1 # WEB-1080p score: 0A score of 0 turns the format off for that profile without deleting it. That is the gentlest override, and it is the one I reach for first.
Groups: Opt In and Opt Out
TRaSH also bundles related CFs into groups: audio formats, HDR, streaming services, unwanted release types. When your profile has a trash_id, Recyclarr syncs the groups that the guide marks as default for that profile. You get them without writing a line.
Two keys change that, under custom_format_groups:
custom_format_groups: skip: - 9d5acd8f1da78dfbae788182f7605200 # [Audio] Audio Formats add: - trash_id: f4f1474b963b24cf983455743aa9906c # [Optional] Movie Versions select_all: trueskip removes a default group. add turns on a non-default group. A group with no default CFs, like Movie Versions, syncs nothing until you list CFs under select or set select_all: true. exclude removes the ones you do not want. Both IDs above are Radarr groups, checked against list custom-format-groups radarr. Sonarr has its own group IDs, so run the same command with sonarr before you copy anything.
One gotcha: a group only assigns scores to the profiles on its own include list. If you add a group and nothing shows up in a hand-built profile, add assign_scores_to with the profile name.
What Recyclarr Touches and What It Leaves Alone
This is the part that decides whether you trust the tool near a library you spent years building.
It manages what is in your config. A CF that is not in your config, or not in a group your profile pulls in, is not touched. A CF you built by hand and named “My Cool Format” stays exactly as you left it.
It overwrites what it manages. If you edit a synced CF in the Sonarr UI, the next sync puts it back. Recyclarr creates missing CFs and updates different ones. That is the feature. If you want a CF under manual control, leave its trash_id out of the config.
Name collisions get adopted. If a CF in your config already exists in Sonarr under the same name, Recyclarr takes it over and updates it. It logs a warning that the CF “already existed in the service and was replaced by Recyclarr”. Your hand-built “HDR10+” would be rewritten that way if the guide has one with the same name.
Deletion is opt-in. delete_old_custom_formats defaults to false. Set it to true, and Recyclarr deletes CFs that it synced earlier and that you later remove from the config, or that the guide drops. It only deletes CFs it created. Your hand-built formats are safe from that setting.
Score resets are broader. reset_unmatched_scores with enabled: true sets the score to 0 for every CF in that profile that Recyclarr does not manage. That includes the formats you scored by hand. List those under except (exact names) or except_patterns (regex) to protect them.
quality_profiles: - trash_id: 72dae194fc92bf828f32cde7744e51a1 # WEB-1080p reset_unmatched_scores: enabled: true except: - My Cool Format except_patterns: - "^\\[Mine\\]"Recyclarr tracks what it created in a state/ folder under /config. Back up that folder together with recyclarr.yml. Sync already adopts same-name custom formats on its own. recyclarr state repair --adopt still exists in v8 but is removed in v9, so you rarely need it.
Quality Sizes and Naming
Two small sections do a lot of quiet work.
quality_definition with a type (series or movie, among the types list qualities sonarr or list qualities radarr prints) sets the min, max, and preferred size for every quality, from the guide’s numbers. Add preferred_ratio (0.0 to 1.0) to slide the preferred marker between min and max. Override one quality with a qualities list:
quality_definition: type: movie qualities: - name: Bluray-1080p min: 5 max: 100 preferred: 80Omitted fields keep the guide values. On Sonarr v5 the sizes live on each quality profile instead of the whole instance, and Recyclarr applies them only to the profiles you list.
media_naming sets the file and folder formats. The keys are the names in the Key column of recyclarr list naming radarr (or sonarr). With rename: true, Sonarr and Radarr start renaming files to that format, so check what your media server expects before you turn it on. If you remove the whole block, Recyclarr leaves your naming alone.
Recyclarr vs the Alternatives
Five ways to get TRaSH data into Sonarr and Radarr. Status checked on 2026-11-20.
| Option | What it is | Where it fits |
|---|---|---|
| By hand in the UI | Paste JSON, type scores | One profile, no updates. Falls behind the guide. |
| Recyclarr | CLI, YAML config, runs on a schedule | You want the config in git and zero UI. |
| Profilarr | Web UI app (v2.3.1) that links databases, including a TRaSH Guides one, and syncs them | You prefer clicking, testing scores, and looking at diffs. |
| Configarr | YAML config like Recyclarr (v1.39.2) | You want Recyclarr-style config plus your own custom formats, or Kubernetes. |
| Notifiarr | Client for notifiarr.com with a “Sync TRaSH profiles” feature | You already run Notifiarr for its other jobs. |
My take: pick Recyclarr if you are comfortable with a text file. The config lives in git, the diff of a change is readable, and the schema in your editor catches typos. Profilarr is the one to try if the idea of YAML makes your eye twitch. Its README lists Radarr v5 and v6 and Sonarr v4 and v5 as supported, so check that against your versions first.
Configarr says it is compatible with Recyclarr templates, and its README lists Radarr v5, v6, and v7. It targets people who want extra custom formats beyond the TRaSH set. Notifiarr is a hosted service with a client, and its README lists TRaSH profile syncing as one of many features. If all you want is the sync, it is a big tent for one trick.
Doing it by hand is fine for exactly one profile that you never plan to touch again. Nobody has ever been in that situation.
Version Gotchas
- Pin
:8. Recyclarr publishes nolatesttag. The unreleased v9 changelog lists the removal ofCRON_SCHEDULEfrom the Docker image, so a blind upgrade would break the cron mode in this post. - Sonarr v5 and Radarr 7 work. Recyclarr v8.8.0 added Sonarr v5 support. Version 8.8.1 fixed a sync failure on Radarr 7 with OIDC login. Update to 8.8.1 or newer if Radarr 7 is your target.
- Old tutorials lie. Settings that older guides use, such as
replace_existing_custom_formats, are gone in v8. The CLI uses--logfor log levels andlistcommands print tables unless you add--raw. - Back up first. Take a Sonarr and Radarr backup (System, Backup) before the first real sync. The undo for a sync is that app backup.
Your 2 AM self will thank you for the backup, and for the preview flag.
Common Questions
Does Recyclarr overwrite custom formats I made myself?
Only if your config manages them. Recyclarr leaves custom formats alone when their trash_id is not in your config. It overwrites a synced custom format on the next run, and it adopts one that has the same name as a configured one. Keep manual formats out of the config.
Do I need to keep the Recyclarr container running?
No. The container only exists to run sync on a schedule, daily by default through CRON_SCHEDULE. You can skip docker compose up -d and run docker compose run --rm recyclarr sync by hand or from your own cron. Recyclarr needs no resident process.
Can Recyclarr manage more than one Sonarr or Radarr?
Yes. Add one named instance per server under sonarr: or radarr:, each with its own base_url and api_key. Then run sync -i <name> to target one, or plain sync for all of them. Each instance keeps its own profiles and state.
What does reset_unmatched_scores actually do?
The reset_unmatched_scores option sets the score to 0 on every custom format in that profile that Recyclarr does not manage. That includes formats you scored by hand. Add those names under except, or a regex under except_patterns, and Recyclarr skips them. Leave the option off if you want a hands-off profile.