Sonarr Episode Retention

Automatically delete old episodes in Sonarr to save disk space. The script keeps a configurable number of the newest episodes per series and automatically deletes older ones.

🎯 Main Features

• Automatic Episode Retention: Deletes old episodes based on configurable limits
• Cross-Season Support: Episode limits work across multiple seasons
• Smart Unmonitoring: Unmonitors old episodes and after deletion
• Flexible Configuration: Config file or environment variables
• Custom Script Integration: Runs automatically on new downloads
• Debug Mode: Safe test runs without changes
• API Testing: Configuration validation

📋 Requirements

• Python 3.6+
• requests library
• Sonarr v3 API
• Configured API connection

🚀 Installation

1. Copy script to Sonarr scripts folder:

cp sonarr-episode-retention.py /path/to/sonarr/scripts/
chmod +x /path/to/sonarr/scripts/sonarr-episode-retention.py

2. Create configuration file (see Configuration)

3. Set up in Sonarr as Custom Script (see Sonarr Setup)

Configuration

Config File (retention.conf)

[API]
url = http://localhost:8989
key = your_sonarr_api_key
url_base =

[Series]
breaking-bad = 10
the-office-us = 15
game-of-thrones = 5

Environment Variables

# API Configuration
API_KEY=your_sonarr_api_key
SONARR_URL=http://localhost:8989
URL_BASE=/sonarr

# Series Configuration
SERIES_breaking-bad=10
SERIES_the-office-us=15
SERIES_game-of-thrones=5

Docker Compose

environment:
  - API_KEY=your_sonarr_api_key
  - SONARR_URL=http://sonarr:8989
  - SERIES_breaking-bad=10
  - SERIES_the-office-us=15

🔧 Usage

As Sonarr Custom Script (Recommended)

# Runs automatically on downloads
/scripts/sonarr-episode-retention.py

Manual Cronjob Mode

# Clean all configured series
/scripts/sonarr-episode-retention.py --custom-script=false

Debug Mode

# Test run without changes
/scripts/sonarr-episode-retention.py --debug

Show Series List

# Display available series with cleanTitle
/scripts/sonarr-episode-retention.py --list-series

📝 Command Line Arguments

Argument	Description	Default
--debug	Debug mode, no changes	False
--config PATH	Path to configuration file	Auto-Detection
--list-series	Show available series	False
--custom-script	Custom Script mode	True

Sonarr Setup

Configure Custom Script

1. Settings → Connect → + → Custom Script
2. Name: Episode Retention
3. On File Import: ✅ Enabled
4. On File Import: ✅ Enabled
5. Path: /scripts/sonarr-episode-retention.py
6. Arguments: (leave empty)

Run Test

1. Click Test in Sonarr
2. Check logs:

✅ Successfully connected to Sonarr API
✅ Found 3 series in configuration
✅ Configuration test completed successfully!

📊 How It Works

Episode Retention Logic

1. Episode Collection: Gets all episodes with files
2. Chronological Sorting: Sorted by season and episode
3. Limit Application: Keeps the last X episodes
4. Old Episode Unmonitoring: Unmonitors episodes before first download
5. Delete + Unmonitor: Deletes old files and unmonitors episodes

Example

Series with 30 episodes, limit: 15

• Keep: Episodes 16-30 (newest 15)
• Delete: Episodes 1-15 (oldest)
• Unmonitor: All episodes before episode 16

🔍 Logging

Log File

• Path: /config/logs/sonarr-episode-retention.txt
• Rotation: Weekly, 4 backups
• Format: YYYY-MM-DD HH:MM:SS LEVEL Message

Log Levels

• INFO: Normal operations
• DEBUG: Detailed information (--debug)
• WARNING: Non-critical issues
• ERROR: Critical errors

Example Logs

2025-09-11 14:30:00 INFO Processing: Breaking Bad
2025-09-11 14:30:01 INFO Series has 50 downloaded episodes, keeping 10, deleting 40
2025-09-11 14:30:02 INFO Unmonitored 5 old episodes
2025-09-11 14:30:10 INFO Successfully processed 40 episodes for deletion

🛠️ Troubleshooting

Common Issues

API connection failed

❌ Failed to connect to Sonarr API

• Check Sonarr URL
• Validate API key
• Test network connection

Series not found

series 'wrong-name' from config not found in sonarr

• Run --list-series for available names
• Use cleanTitle instead of title

No series configuration

⚠️  No series configuration found

• Check config file
• Validate environment variables

Collect Debug Information

# Full debug output
/scripts/sonarr-episode-retention.py --debug --list-series

# Test mode
/scripts/sonarr-episode-retention.py --debug

🔒 Security

Read-Only Test

• Test Events: Only GET requests, no changes
• Debug Mode: Simulates actions without execution
• Validation: Checks all inputs before processing

Backup Recommendations

• Sonarr Database: Regular backups
• Media Files: Backup before first use
• Config Files: Version control configuration

🔄 Environment Variable Priority

1. Environment Variables (highest priority)
2. Config File
3. Default Values (lowest priority)

📈 Performance

Optimizations

• Batch Operations: Efficient API usage
• Smart Filtering: Only process relevant episodes
• Robust Error Handling: Skips problematic entries

Typical Runtime

• 10 episodes: ~2-5 seconds
• 100 episodes: ~10-30 seconds
• 1000 episodes: ~1-3 minutes

📚 Example Scenarios

Scenario 1: Add New Series

# Via config file
echo "new-series = 12" >> /scripts/retention.conf

# Via environment variable
export SERIES_new-series=12

Scenario 2: Docker Container

services:
  sonarr:
    environment:
      - API_KEY=${SONARR_API_KEY}
      - SONARR_URL=http://sonarr:8989
      - SERIES_breaking-bad=10
      - SERIES_the-office-us=15

Scenario 3: Cronjob

# Daily at 3 AM
0 3 * * * /scripts/sonarr-episode-retention.py --custom-script=false

🔗 See Also

• Sonarr Custom Scripts Documentation
• Sonarr API Documentation
• Season Unmonitor Script