Sonarr
Smart PVR for automated TV series management and quality upgrades
Sonarr is a PVR (Personal Video Recorder) for Usenet and BitTorrent users. It monitors multiple RSS feeds for new episodes of your favorite shows and automatically grabs, sorts, and renames them. Sonarr can also be configured to automatically upgrade the quality of files already downloaded when a better quality format becomes available.
📺 Automatic Series Monitoring
Track your favorite TV shows and automatically download new episodes as they become available
⚡ Quality Management
Define preferred quality profiles and automatically upgrade existing episodes to better quality versions
📅 Calendar Integration
Visual calendar showing upcoming and aired episodes with at-a-glance schedule overview
🔍 TheTVDB Integration
Search and add new series from TheTVDB with comprehensive metadata and episode information
📁 Automatic Organization
Rename and organize files with customizable naming patterns for consistent library structure
🔗 Download Client Support
Works with qBittorrent, Deluge, SABnzbd, NZBGet, rTorrent, and Transmission
🔔 Notification System
Get notified when episodes are grabbed, downloaded, or upgraded via Discord, Slack, Email, and more
⚙️ Custom Scripts
Run custom scripts on grab, download, rename, or import events for advanced automation
Installation
Prerequisites
- QuickBox Pro v3 installed and configured
- Download client installed (qBittorrent, Deluge, rTorrent, etc.)
- Media storage location configured (
/home/username/Media/TV) - User account created on the server
What You Get
- Per-user installation with isolated configurations
- Automatic integration with your download clients
- Pre-configured nginx reverse proxy with SSL
- Auto-generated ports and API keys for security
- Systemd service for automatic startup and management
Basic Installation
Install Sonarr v4 (stable) for a specific user:
qb install sonarr -u usernameSonarr v4 is Now Default
Sonarr v4 is the current stable version installed by default. The --v4 flag is only used for updating existing v3 installations to v4—not for new installs.
Installation Commands
-u, --usernameRequiredSpecify the user for installation
-u john--nightlyInstall develop branch (nightly builds) for cutting-edge features
--4kInstall dedicated 4K instance (Sonarr4K) with separate config and port
--v4Upgrade existing v3 to v4 (update command only - not for new installs)
4K Instance
The --4k flag creates a separate Sonarr4K instance dedicated to 4K/UHD content with its own port, configuration directory (~/.config/Sonarr4K), and quality profiles—perfect for managing standard and 4K libraries separately without conflicts.
Update Branch Handling
When you run qb update sonarr -u username, QuickBox automatically detects your current branch (main or develop) from config.xml and updates accordingly. You don’t need to specify --nightly unless you want to switch branches.
Directory Structure
Configuration Details
Standard instance:
- Install location:
/opt/username/Sonarr/ - Config directory:
~/.config/Sonarr/ - Database:
~/.config/Sonarr/sonarr.db - Service:
sonarr@username.service - Default port:
8989(auto-generated if in use) - SSL port:
9898(auto-generated if in use)
4K instance (—4k flag):
- Install location:
/opt/username/Sonarr4K/ - Config directory:
~/.config/Sonarr4K/ - Database:
~/.config/Sonarr4K/sonarr.db - Service:
sonarr4k@username.service - Ports: Auto-generated (typically
8990+)
Upgrading from v3 to v4
Important Migration Information
If you have an existing Sonarr v3 installation, you must upgrade to v4 using the --v4 flag. This is a one-time migration that updates your database schema.
Upgrade Command
qb update sonarr -u username --v4Pre-Upgrade Checklist
Before Upgrading
- Backup your database:
~/.config/Sonarr/sonarr.db - Stop any manual searches or active downloads
- Note your current configuration (ports, API key, indexers)
- Verify you have sufficient disk space
Upgrade Process
- Service is stopped automatically
- Latest v4 package is downloaded and installed
- Database schema is migrated to v4 format
- Configuration and settings are preserved
- Service restarts automatically with v4
Database Backup
Always backup before upgrading: cp ~/.config/Sonarr/sonarr.db ~/.config/Sonarr/sonarr.db.v3-backup
Accessing Sonarr
After installation, Sonarr is accessible through QuickBox’s nginx reverse proxy with SSL:
QuickBox Dashboard Integration
Sonarr is automatically integrated into your QuickBox dashboard. Find it in the Application Control panel with port, API key, and status information. Click the LAUNCH icon to open the web interface, or use the Package Management tab to install/remove applications.
Network Configuration
QuickBox automatically configures:
- URL Base:
/username/sonarr(or/username/sonarr4k) - Bind Address:
127.0.0.1(local only - proxied through nginx) - Port: Auto-assigned (typically
8989for standard,8990+for 4K) - SSL: Handled by nginx reverse proxy (port 443)
- Authentication: Initially set to
None(configure on first access)
Initial Configuration
1. Set up Authentication
Security First
Configure authentication immediately after installation if your server is accessible from the internet.
- Navigate to Settings → General
- Under Security, configure:
- Authentication Method:
Forms(recommended) orBasic - Username: Your chosen username
- Password: Strong password
- Authentication Method:
2. Configure Download Client
Sonarr needs a download client to grab releases. QuickBox configures clients with SSL through nginx.
Steps:
- Go to Settings → Download Clients
- Click Add (+) button
- Select your client (qBittorrent, Deluge, rTorrent, etc.)
- Enable Show Advanced to access URL Base field
- Enter connection details from the table below
Download Client Configuration
QuickBox-specific connection details for common download clients
Deluge
443/username/delugeFlood
443/username/floodNZBGet
443/username/nzbgetqBittorrent
443/qbittorrentrTorrent
443SABnzbd
443/username/sabnzbdTransmission
443/username/transmission- Click Test to verify connection
- Click Save if test succeeds
Download Client Categories
Configure categories in your download client (e.g., tv-sonarr) to isolate Sonarr downloads and set specific paths automatically.
3. Add Indexers via Prowlarr (Recommended)
Prowlarr provides centralized indexer management across all *arr applications:
- Install Prowlarr:
qb install prowlarr -u username - In Prowlarr, navigate to Settings → Apps
- Click Add (+) and select Sonarr
- Enter:
- Sonarr URL:
http://localhost:8989/username/sonarr - API Key: Found in Sonarr → Settings → General → Security
- Sonarr URL:
- Click Test then Save
- Add indexers in Prowlarr—they automatically sync to Sonarr
Alternative: Manual indexers
- Go to Settings → Indexers → Add (+)
- Add trackers/usenet indexers individually
4. Set Root Folder
Define where Sonarr should store TV shows:
- Navigate to Settings → Media Management
- Click Root Folders
- Click Add Root Folder
- Enter path (e.g.,
/home/username/Media/TV) - Click OK
Recommended structure:
- Standard instance:
/home/username/Media/TV - 4K instance:
/home/username/Media/TV-4K
5. Quality Profiles & Upgrades
Configure quality preferences and automatic upgrades:
- Navigate to Settings → Profiles
- Edit existing profile or create new one
- Configure:
- Upgrade Until: Maximum quality (e.g.,
Bluray-1080p) - Upgrades Allowed: ✓ Enabled
- Cutoff: When to stop upgrading
- Upgrade Until: Maximum quality (e.g.,
- Click Save
Example workflow:
- Episode airs → Download
HDTV 720p - Web release available → Upgrade to
WEBDL 1080p - Blu-ray released → Upgrade to
Bluray 1080p(cutoff reached, stop upgrading)
Smart Upgrading Strategy
Set upgrade cutoffs to prevent endless upgrading. For example, setting cutoff to Bluray-1080p prevents automatic upgrades to massive 4K remuxes unless you specifically want them. This saves bandwidth and storage space.
File Naming Configuration
Recommended settings for consistent library organization:
Navigate to Settings → Media Management → File Management:
Example output:
- Standard:
The Office - S02E05 - Halloween WEBDL-1080p.mkv - Daily:
The Daily Show - 2024-12-24 - Holiday Special HDTV-720p.mkv - Anime:
Attack on Titan - S01E13 - 013 - Primal Desire Bluray-1080p.mkv
Adding TV Series
- Click Series in the main navigation
- Click Add New button
- Search for your show by name
- Select the series from search results
- Configure options:
- Root Folder: Where to save the show
- Quality Profile: Desired quality settings
- Monitor: Which episodes to track (see below)
- Series Type: Standard, Daily, or Anime
- Click Add Series
Monitoring Options
Smart Monitoring
Use Future Episodes for ongoing shows you’re already caught up on to avoid re-downloading existing episodes. For new shows or filling gaps, use Missing Episodes or All Episodes.
Service Management
Sonarr runs as a systemd service for reliability and automatic startup.
Service Commands
4K instance commands:
Replace sonarr with sonarr4k in all commands above:
systemctl status sonarr4k@username
systemctl restart sonarr4k@username
journalctl -u sonarr4k@username -fAuto-Start on Boot
QuickBox automatically enables Sonarr to start on boot. You don’t need to run systemctl enable manually unless you’ve previously disabled it.
Troubleshooting
Sonarr Won’t Start
Check These First
- Check service logs:
journalctl -u sonarr@username -f - Verify port availability:
grep -E '<Port>' ~/.config/Sonarr/config.xml - Check for database corruption
- Ensure config directory permissions are correct
Solutions
- Restart the service:
systemctl restart sonarr@username - Fix permissions:
qb fix permissions -u username - Restore database backup if corrupted
- Check for conflicting port usage with other services
View detailed logs:
journalctl -u sonarr@username --since "10 minutes ago" --no-pagerDownloads Not Appearing
Common Issues
- No releases found in manual search
- Episodes not automatically downloading
- Download client connection errors (qBittorrent, Deluge, etc.)
- Series shows as monitored but nothing happens
How to Fix
- Verify indexers: Settings → Indexers → Test or check Prowlarr
- Test download client: Settings → Download Clients → Test
- Ensure series/episodes are monitored (blue icons on series page)
- Try manual search: Click episode → Manual Search icon
- Check quality profile cutoffs haven't been reached
Permission Issues
If Sonarr can’t access files or directories:
# Fix all user permissions
qb fix permissions -u username
# Restart Sonarr
systemctl restart sonarr@username
# Verify ownership
ls -la ~/.config/Sonarr/Common Permission Problems
Permission issues often occur after manually moving files or changing directory ownership. The qb fix permissions command resets ownership recursively for all user directories.
Database Corruption
Symptoms
- Sonarr won't start with database errors in logs
- Series or episodes disappearing randomly
- Settings not saving properly
- Constant crashes or unexpected behavior
Recovery Steps
- Stop service:
systemctl stop sonarr@username - Backup current DB:
cp ~/.config/Sonarr/sonarr.db ~/.config/Sonarr/sonarr.db.corrupt - Restore from backup if available
- Or reinstall:
qb reinstall sonarr -u username(preserves DB) - Last resort: Delete DB and reconfigure from scratch
Check database integrity:
sqlite3 ~/.config/Sonarr/sonarr.db "PRAGMA integrity_check;"Indexer Rate Limiting
If you’re getting rate limit errors from indexers:
- Reduce RSS sync interval: Settings → Indexers → Options → RSS Sync Interval (increase to 30-60 minutes)
- Use Prowlarr for centralized rate limit management
- Remove duplicate or redundant indexers
- Consider premium/VIP indexer accounts for higher limits
Best Practices
Do
- Use Prowlarr for centralized indexer management across all *arr apps
- Set reasonable quality profiles—avoid unnecessary 4K downloads if you don't need them
- Monitor only shows you actually want to prevent excessive bandwidth usage
- Configure proper file naming (Settings → Media Management) for consistent library organization
- Set up automatic backups of your Sonarr database (
~/.config/Sonarr/sonarr.db) - Use download client categories (e.g.,
tv-sonarr) to separate Sonarr downloads - Set upgrade cutoffs (e.g., Bluray-1080p) to prevent endless quality chasing
- Enable notifications (Discord, Telegram, etc.) to track downloads and failed grabs
- Use separate 4K instance (
--4kflag) for 4K content management
Don't
- Don't monitor every episode of every show—be selective to save bandwidth and storage
- Don't set upgrade cutoff too high (4K remuxes are 50-100GB+ and may not be necessary)
- Don't use too many indexers—causes rate limits and excessive API hits
- Don't download to system drive—use dedicated media storage (
/home/username/Media/TV) - Don't ignore failed download warnings—investigate and resolve issues promptly
- Don't mix standard and 4K content in same instance—use separate 4K instance
- Don't disable authentication if Sonarr is accessible from the internet
- Don't ignore database backups—corruption can happen and cause permanent data loss
- Don't use Jackett if Prowlarr is available—Prowlarr is the modern replacement
Use Cases & Workflows
Automated TV Collection
Perfect for building and maintaining a complete TV library:
- New series monitoring: Add shows and automatically download all past episodes
- Weekly episode tracking: Catch new episodes within minutes of release
- Quality upgrades: Automatically upgrade from HDTV → WEBDL → Bluray
- Library organization: Consistent naming and folder structure across thousands of episodes
Multiple Quality Tiers
Manage different quality standards with separate instances:
| Quality Tier | Configuration |
|---|---|
Standard HD | Main Sonarr instance with 720p/1080p profiles for general viewing |
4K/UHD | 4K instance ( --4k flag) with separate root folder (/home/username/Media/TV-4K) |
Anime | Dedicated instance with anime naming format and specific indexers |
Integration with Media Servers
Sonarr works seamlessly with:
- Plex: Automatic library updates when new episodes are imported
- Jellyfin: Native integration for metadata and library scanning
- Emby: Real-time notifications when new content is added
Request Management Workflow
Combine with request management systems:
- User requests show in Overseerr or Jellyseerr
- Request automatically adds series to Sonarr
- Sonarr searches indexers and sends to download client
- Media server notifies user when available
- Sonarr continues monitoring for future episodes
Related Applications
Sonarr integrates seamlessly with the QuickBox ecosystem:
Indexers
Download Clients
Request Management
Subtitles
Additional Resources
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.