arr-shrink

Tools to manage and remove oversized media files from your Sonarr and Radarr libraries. Perfect for users who have adjusted their quality settings and need to clean up existing large files.

⚠️ IMPORTANT SAFETY WARNING ⚠️

arr-shrink permanently deletes media files from your disk.

• Deleted files cannot be recovered without backups
• Always test with dry-run mode first
• Consider backing up important files before execution
• Understand that re-downloads depend on availability - if files are no longer available from your indexers, they may be permanently lost
• This process is irreversible - make sure you understand what will be deleted

Prerequisites

• Python 3.6 or higher
• Sonarr v3 or Radarr v3 (API v3 compatibility required)
• Network access to your Sonarr/Radarr instance
• File system access to your media library
• Valid API keys for your applications

Compatibility

• Sonarr: v3.x and newer (uses API v3 endpoints)
• Radarr: v3.x and newer (uses API v3 endpoints, confirmed working on v5.x)
• Python: 3.6+ required, tested on 3.8-3.11
• OS: Windows 10+, macOS 10.14+, Linux (most distributions)

Why Use These Scripts?

• You've changed quality profiles to prefer smaller file sizes
• You want to replace large 4K files with more reasonable 1080p versions
• You need to free up disk space by removing unnecessarily large files
• You're tired of manually deleting files to trigger re-downloads

These tools automate the process of identifying and removing oversized media files so Sonarr and Radarr can download replacements according to your current quality settings.

Features

• Size-Based Targeting: Identifies files exceeding your specified size threshold
• Safe Execution: Runs in dry-run mode by default to preview changes
• Path Verification: Includes a utility to test path conversion settings
• Batch Processing: Controls the deletion pace to prevent system overload
• Processing History: Tracks deleted files to prevent reprocessing
• Detailed Logging: Shows exactly what's happening at each step
• Cross-Platform: Works on Windows, macOS, and Linux

Installation

1. Download the scripts from this repository
2. Install dependencies:

   pip install requests

3. Configure the scripts by editing the settings at the top of each file

Configuration

Finding Your API Key

Sonarr:

1. Go to Settings → General
2. Copy the API Key value

Radarr:

1. Go to Settings → General
2. Copy the API Key value

Basic Configuration

Edit the configuration section at the top of each script:

# Sonarr/Radarr connection details
SONARR_URL = 'http://xxx.xxx.xxx.xxx:8989'  # Your Sonarr URL
RADARR_URL = 'http://xxx.xxx.xxx.xxx:7878'  # Your Radarr URL
API_KEY = 'xxxxxx'                          # Your API key

# File size threshold
MAX_SIZE_GB = 4.0                           # Maximum episode size in GB (Sonarr)
MAX_SIZE_GB = 10.0                          # Maximum movie size in GB (Radarr)

# Processing options
BATCH_SIZE = 5                              # Number of files to process in each batch
DELAY_SECONDS = 10                          # Delay between batches in seconds

Path Configuration

The most critical configuration is the MEDIA_PATH_PREFIX setting, which tells the script how to access your media files.

Common Path Configuration Examples

Windows - Local Media:

MEDIA_PATH_PREFIX = "C:\\Media\\TV Shows\\"      # Local drive
MEDIA_PATH_PREFIX = "D:\\Plex\\TV Shows\\"       # Different drive

Windows - Network Share:

MEDIA_PATH_PREFIX = "\\\\192.168.1.100\\media\\TV Shows\\"    # IP address
MEDIA_PATH_PREFIX = "\\\\MediaServer\\shares\\TV Shows\\"     # Server name

Linux/Mac - Local Media:

MEDIA_PATH_PREFIX = "/home/user/media/TV Shows/"    # User home directory
MEDIA_PATH_PREFIX = "/mnt/media/TV Shows/"          # Mounted drive
MEDIA_PATH_PREFIX = "/opt/media/TV Shows/"          # System directory

Docker Users:

# If running script on host but media is in container path:
MEDIA_PATH_PREFIX = "/host/path/to/TV Shows/"
# Match the actual host filesystem path, not the container path

Important: The script converts Sonarr/Radarr's internal paths to your actual filesystem paths. If you're unsure, use the --verify-paths option to test your configuration.

Usage

Step 1: Verify Path Configuration

Always start here! Before running in execution mode, verify your path settings:

python sonarr-shrink.py --verify-paths
python radarr-shrink.py --verify-paths

This will test if the script can find your media files. If it shows "NO" for files that exist, adjust your MEDIA_PATH_PREFIX setting.

Step 2: Dry Run Mode (Default)

Run in dry-run mode to see what would be deleted without actually deleting anything:

python sonarr-shrink.py
python radarr-shrink.py

Expected Output:

Found 15 oversized episodes
DRY RUN - No files will be deleted
Would delete: Breaking Bad - S01E01
  File: /media/TV Shows/Breaking Bad/Season 01/Breaking Bad - S01E01.mkv
  Size: 8.54 GB
  Quality: Bluray-1080p

Step 3: Execution Mode

When you're ready to delete files:

python sonarr-shrink.py --execute
python radarr-shrink.py --execute

The script will ask for confirmation before proceeding with deletions.

What Happens After Files Are Deleted?

Understanding the process helps set proper expectations:

1. Sonarr/Radarr will detect missing files during the next library scan
2. Episodes/Movies will show as "Missing" in the UI
3. You can trigger manual searches to find replacements
4. New downloads will follow your current quality profile
5. Files may not be re-downloadable if they're no longer available on your indexers

Important: This process assumes your indexers still have the content available. Rare, older, or region-specific content may not be re-downloadable.

Typical Workflow

1. Change your quality settings in Sonarr/Radarr to prefer smaller file sizes
2. Verify path configuration with the --verify-paths option
3. Run the script in dry-run mode to preview which files will be removed
4. Execute the script to delete oversized files
5. Manually refresh your library in Sonarr/Radarr:
   • Sonarr: Go to Series → [series name] → Refresh & Scan
   • Radarr: Go to Movies → [movie name] → Refresh & Scan
6. Trigger searches for missing content:
   • Sonarr: Activity → Queue → Search All Missing
   • Radarr: Movies → Missing → Search All Missing
7. Monitor downloads and verify quality profiles are working as expected

Performance & System Impact

Consider these factors when running the scripts:

• Network I/O: Each file requires API calls and file system checks
• Batch processing: Default 5 files per batch with 10-second delays
• Large libraries: Consider running overnight for 1000+ files
• System load: Monitor CPU/disk usage during execution

Recommended Settings for Large Libraries:

BATCH_SIZE = 3        # Smaller batches for heavily loaded systems
DELAY_SECONDS = 15    # Longer delays to reduce system stress

For Very Large Libraries (5000+ files):

BATCH_SIZE = 2        # More conservative processing
DELAY_SECONDS = 20    # Longer delays between batches

Understanding History and Tracking

The tool keeps detailed history files that track processed media:

• Sonarr: sonarr-shrink-history.json
• Radarr: radarr-shrink-history.json

History File Contains:

• The date of the last run
• Total number of processed files
• Details about each processed file including:
  • Series/movie name and episode information
  • Original file size and path
  • Date when file was processed
  • Quality information

Benefits of History Tracking:

• Prevents reprocessing the same files in future runs
• Provides an audit trail of what was deleted
• Helps with troubleshooting and recovery
• Useful for understanding script behavior over time

Recovery & Rollback

If something goes wrong:

1. Check the history file for deleted file details and timestamps
2. Restore from backup if you created one beforehand
3. Manually search for specific episodes/movies in Sonarr/Radarr
4. Review indexer settings to ensure content is still available
5. Check download client for any stuck or failed downloads

The history file helps with recovery by providing:

• Exact file paths that were deleted
• Timestamps of deletions
• Original file sizes and quality information
• Series/movie identification details

Common Issues & Solutions

Connection Issues

Problem	Solution
"Failed to connect"	Verify URL format includes http:// or https://
"Unauthorized"	Check API key is correct and has proper permissions
"Connection refused"	Ensure Sonarr/Radarr is running and accessible
Timeout errors	Check network connectivity and firewall settings

Path Issues

Problem	Solution
"File does not exist"	Run --verify-paths to test path conversion
All files show as non-existent	Check MEDIA_PATH_PREFIX setting matches your actual paths
Mixed results (some found, some not)	May indicate network share, permission, or mounting issues
Permission denied	Ensure script has read/write access to media folders

No Files Found

Problem	Solution
No oversized files reported	Check your size threshold - try lowering MAX_SIZE_GB
Files exist but not detected	Verify you have media that actually exceeds the threshold
Empty library response	Check file permissions and API connectivity
Version compatibility issues	Ensure you're using Sonarr/Radarr v3 (API v3)

Processing Issues

Problem	Solution
Script stops mid-processing	Check available disk space and system resources
Slow performance	Reduce BATCH_SIZE or increase DELAY_SECONDS
Network timeouts	Increase delays between API calls
Memory issues	Process smaller batches or restart script periodically

API-Specific Troubleshooting

API Compatibility: These scripts use API v3 endpoints, which remain stable across application versions.

Custom Ports: Ensure your URL includes the correct port (default: Sonarr 8989, Radarr 7878).

Version Issues: If you encounter API errors, verify your application is running and accessible, regardless of version.

Tips and Best Practices

• Start with a higher threshold and gradually lower it to control impact
• Always run in dry-run mode first to preview changes
• Test with a small subset before processing large libraries
• Back up important or rare files before running in execution mode
• Monitor system resources during processing
• Run during off-peak hours for large libraries
• Check indexer availability for content you're planning to re-download
• Review quality profiles before deleting to ensure suitable replacements exist
• Keep history files as they provide valuable audit trails

Advanced Usage

Custom Size Thresholds for Different Content

You might want different size limits for different types of content. Consider running the script multiple times with different configurations:

# First run: Very large files (>15GB)
MAX_SIZE_GB = 15.0

# Second run: Large files (>8GB) 
MAX_SIZE_GB = 8.0

# Third run: Medium files (>4GB)
MAX_SIZE_GB = 4.0

Selective Processing

The scripts process all oversized files they find. For more selective processing:

1. Use higher size thresholds to target only the largest files
2. Review the dry-run output carefully
3. Consider manually deleting specific files instead of batch processing

Contributing

If you encounter bugs or have suggestions for improvements:

1. Check existing issues to see if the problem is already reported
2. Provide detailed information about your setup and the issue
3. Include relevant log output and configuration details
4. Test with the latest version before reporting

License

MIT License - See LICENSE file for details.

Acknowledgments

• The Sonarr and Radarr development teams for their excellent APIs
• The media management community for feedback and testing
• Contributors who have helped improve these scripts