Brian Pooe 3247b61b5b fix: using codex to polish

2026-02-14 22:09:41 +02:00

8.8 KiB

Raw Blame History

Recyclarr Configuration Guide

Recyclarr automatically synchronizes TRaSH Guides quality profiles and custom formats to your Sonarr and Radarr instances.

Quick Start

1. Copy Configuration Template

# Copy the template to your recyclarr config directory
./substitute_env.sh docker-compose-files/recyclarr_template.yml /volume1/docker/appdata/recyclarr/recyclarr.yml

# Edit with your API keys
nano /volume1/docker/appdata/recyclarr/recyclarr.yml

2. Get API Keys

Sonarr:

Open Sonarr web interface: http://your-nas-ip:8989
Go to: Settings → General → Security
Copy the API Key

Radarr:

Open Radarr web interface: http://your-nas-ip:7878
Go to: Settings → General → Security
Copy the API Key

3. Configure Base URLs

CRITICAL: Use Docker service names, NOT localhost!

# ✅ Correct - Uses service name
sonarr:
  web-1080p-v4:
    base_url: http://sonarr:8989
    api_key: your_sonarr_api_key_here

radarr:
  uhd-bluray-web:
    base_url: http://radarr:7878
    api_key: your_radarr_api_key_here

# ❌ Wrong - localhost doesn't work in Docker
sonarr:
  web-1080p-v4:
    base_url: http://localhost:8989  # Won't work!

Why? Inside the recyclarr container, localhost refers to itself, not the host or other containers.

Configuration Example

Complete Working Configuration

sonarr:
  web-1080p-v4:
    base_url: http://sonarr:8989
    api_key: abc123def456...  # Your actual API key
    delete_old_custom_formats: true
    replace_existing_custom_formats: true
    include:
      - template: sonarr-quality-definition-series
      - template: sonarr-v4-quality-profile-web-1080p
      - template: sonarr-v4-custom-formats-web-1080p

  web-2160p-v4:
    base_url: http://sonarr:8989
    api_key: abc123def456...  # Same API key
    delete_old_custom_formats: true
    replace_existing_custom_formats: true
    include:
      - template: sonarr-quality-definition-series
      - template: sonarr-v4-quality-profile-web-2160p
      - template: sonarr-v4-custom-formats-web-2160p

radarr:
  uhd-bluray-web:
    base_url: http://radarr:7878
    api_key: xyz789ghi012...  # Your actual API key
    delete_old_custom_formats: true
    replace_existing_custom_formats: true
    include:
      - template: radarr-quality-definition-movie
      - template: radarr-quality-profile-uhd-bluray-web
      - template: radarr-custom-formats-uhd-bluray-web

  hd-bluray-web:
    base_url: http://radarr:7878
    api_key: xyz789ghi012...  # Same API key
    delete_old_custom_formats: true
    replace_existing_custom_formats: true
    include:
      - template: radarr-quality-definition-movie
      - template: radarr-quality-profile-hd-bluray-web
      - template: radarr-custom-formats-hd-bluray-web

Testing Configuration

1. Validate Config File

# List configured instances
docker exec recyclarr recyclarr config list

Expected output:

Sonarr Instances:
  - web-1080p-v4
  - web-2160p-v4

Radarr Instances:
  - uhd-bluray-web
  - hd-bluray-web

2. Preview Sync (Dry Run)

# Preview changes without applying
docker exec recyclarr recyclarr sync --preview

This shows what would change without actually modifying anything.

3. Actually Sync

# Apply changes to Sonarr and Radarr
docker exec recyclarr recyclarr sync

4. Check Logs

# View recyclarr logs
docker logs recyclarr

# Follow logs in real-time
docker logs -f recyclarr

Automatic Sync Schedule

Recyclarr runs on a cron schedule defined in the container. By default, it syncs daily.

To modify the schedule, you would need to customize the container configuration (advanced).

For manual syncs:

docker exec recyclarr recyclarr sync

Common Issues

Issue: "base_url must start with 'http' or 'https'"

Cause: The base_url is empty or malformed.

Fix:

# Wrong
base_url: localhost:8989
base_url:  # Empty

# Correct
base_url: http://sonarr:8989

Issue: "Connection refused" or "Cannot connect"

Possible causes:

Service names are wrong
Containers not on same network
Sonarr/Radarr not running

Fix:

# Check containers are running
docker ps | grep -E "sonarr|radarr|recyclarr"

# Check network connectivity
docker exec recyclarr ping sonarr
docker exec recyclarr ping radarr

# Check Sonarr is responding
docker exec recyclarr wget -qO- http://sonarr:8989/ping

Issue: "Unauthorized" or "Invalid API key"

Cause: Wrong API key or permissions issue.

Fix:

Get correct API key from Sonarr/Radarr (Settings → General → Security)
Copy-paste carefully (no extra spaces)
Ensure API key has full permissions

Issue: Config file not found

Cause: File not in correct location.

Fix:

# Check file exists
docker exec recyclarr ls -la /config

# Expected location inside container
/config/recyclarr.yml

On host, this maps to:

{{DOCKERCONFDIR}}/recyclarr/recyclarr.yml

Quality Profiles

What Recyclarr Syncs

For Sonarr:

Quality definitions (file size limits)
Quality profiles (which qualities to allow)
Custom formats (preferences for releases)
Custom format scores (prioritization)

For Radarr:

Quality definitions
Quality profiles
Custom formats
Custom format scores

Available TRaSH Templates

Sonarr:

sonarr-quality-definition-series - File size limits
sonarr-v4-quality-profile-web-1080p - 1080p WEB profile
sonarr-v4-quality-profile-web-2160p - 4K WEB profile
sonarr-v4-custom-formats-web-1080p - 1080p custom formats
sonarr-v4-custom-formats-web-2160p - 4K custom formats

Radarr:

radarr-quality-definition-movie - File size limits
radarr-quality-profile-hd-bluray-web - HD Bluray/WEB
radarr-quality-profile-uhd-bluray-web - 4K Bluray/WEB
radarr-custom-formats-hd-bluray-web - HD custom formats
radarr-custom-formats-uhd-bluray-web - 4K custom formats

Custom Formats

Common Custom Formats

Recyclarr applies TRaSH Guide custom formats to improve release selection:

Quality Improvements:

Prefer proper/repack releases
Avoid bad dual audio groups
Prefer streaming optimized releases

HDR/Audio:

DV (Dolby Vision) handling
HDR10+ support
Audio codec preferences

Release Groups:

Prefer scene/p2p groups
Avoid obfuscated releases
Filter low-quality encodes

Customizing Scores

In your config, you can adjust scores:

custom_formats:
  - trash_ids:
      - 9f6cbff8cfe4ebbc1bde14c7b7bec0de # IMAX Enhanced
    assign_scores_to:
      - name: UHD Bluray + WEB
        score: 100  # Higher score = higher priority

Maintenance

Manual Sync

# Sync all instances
docker exec recyclarr recyclarr sync

# Sync specific instance
docker exec recyclarr recyclarr sync sonarr web-1080p-v4

Update Recyclarr

Recyclarr updates are reported by Diun. Apply image updates manually after review.

Manual update:

docker-compose -f docker-compose.arr-stack.yml pull recyclarr
docker-compose -f docker-compose.arr-stack.yml up -d recyclarr

View Current Settings

Check what's currently configured in Sonarr/Radarr:

Settings → Profiles → Quality Profiles
Settings → Profiles → Custom Formats

Best Practices

Start with Templates
- Use TRaSH templates as baseline
- Customize only if needed
Test with Preview
- Always preview before syncing
- Review changes carefully
Backup Before Syncing
- Backup Sonarr/Radarr databases
- Easy rollback if needed
Monitor First Sync
- Watch logs during initial sync
- Verify profiles in UI after sync
Keep It Simple
- Don't over-customize initially
- TRaSH defaults work well for most

Advanced Configuration

Multiple Instances

You can configure multiple Sonarr/Radarr instances:

sonarr:
  instance-1:
    base_url: http://sonarr:8989
    api_key: key1

  instance-2:
    base_url: http://sonarr-4k:8989
    api_key: key2

Instance-Specific Templates

Different quality settings per instance:

sonarr:
  web-1080p:
    include:
      - template: sonarr-v4-quality-profile-web-1080p

  web-2160p:
    include:
      - template: sonarr-v4-quality-profile-web-2160p

Resources

TRaSH Guides: https://trash-guides.info/
Recyclarr Wiki: https://recyclarr.dev/
Recyclarr GitHub: https://github.com/recyclarr/recyclarr
TRaSH Discord: https://trash-guides.info/discord

Troubleshooting Checklist

Config file exists at correct location
Base URLs use service names (not localhost)
API keys are correct and complete
Sonarr/Radarr are running and healthy
Containers are on same Docker network
No typos in configuration
YAML syntax is valid (proper indentation)

Last Updated: 2026-02-14

8.8 KiB Raw Blame History

Recyclarr Configuration Guide

Quick Start

1. Copy Configuration Template

2. Get API Keys

3. Configure Base URLs

Configuration Example

Complete Working Configuration

Testing Configuration

1. Validate Config File

2. Preview Sync (Dry Run)

3. Actually Sync

4. Check Logs

Automatic Sync Schedule

Common Issues

Issue: "base_url must start with 'http' or 'https'"

Issue: "Connection refused" or "Cannot connect"

Issue: "Unauthorized" or "Invalid API key"

Issue: Config file not found

Quality Profiles

What Recyclarr Syncs

Available TRaSH Templates

Custom Formats

Common Custom Formats

Customizing Scores

Maintenance

Manual Sync

Update Recyclarr

View Current Settings

Best Practices

Advanced Configuration

Multiple Instances

Instance-Specific Templates

Resources

Troubleshooting Checklist

8.8 KiB

Raw Blame History