
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
Install from the Dashboard
Open App Dashboard → Package Management (/), find Sonarr in the catalog (browse Media Management or search), and click Install. The dashboard streams the install log live and Sonarr appears in your Application Control panel when it finishes. Reinstall and Remove are in the same Package Management panel. To update, use the amber Update badge on the Sonarr row in the App Dashboard.
In the install dialog you can pick the release channel — Stable (default) or Nightly. Stable follows Sonarr’s main branch, which carries Sonarr 4. Nightly follows the develop branch, which carries Sonarr 5. Switching the channel later and updating moves Sonarr to that channel’s latest build; the steps are in Move to Sonarr 5. See Channels & Versions for how channels work.
For a dedicated 4K library, install Sonarr4K — a separate instance with its own port, configuration directory (~/), and quality profiles, so your standard and 4K libraries never conflict. It appears as its own catalog entry in Package Management; on the CLI it is the --4k flag on qb install sonarr (see below).
What you see and can manage is gated by your account: admins manage any user’s apps; regular users manage their own. For the full package flow see App Management.
Install and manage from the CLI
The CLI runs the same scripts as the Dashboard and is the full power-user/automation surface. Install Sonarr on the stable channel for a specific user:
qb install sonarr -u usernameThe complete command set:
| Command | Description |
|---|---|
| qb install sonarr -u username | Install Sonarr on the stable channel (main branch, Sonarr 4) with automatic configuration |
| qb install sonarr -u username --nightly | Install on the nightly channel (develop branch), which carries Sonarr 5 |
| qb install sonarr -u username --4k | Install a separate 4K instance (Sonarr4K) for high-resolution content |
| qb install sonarr -u username --nightly --4k | Install the 4K instance on the nightly branch |
| qb reinstall sonarr -u username | Remove and install Sonarr fresh (deletes its config folder and backups, so take a Full Backup first) |
| qb update sonarr -u username | Update on the channel Sonarr is set to (read from config.); never installs a lower major than the one you run |
| qb update sonarr -u username --nightly | Switch to the nightly channel and update: a Sonarr 4 install moves to Sonarr 5 (see Move to Sonarr 5) |
| qb remove sonarr -u username | Remove the standard installation |
| qb remove sonarr -u username --4k | Remove the 4K instance |
| qb help sonarr | Display comprehensive help information |
| Option | Description | Example |
|---|---|---|
-u, --usernameRequired | Specify the user for installation -u john | -u john |
--nightly | Use the develop branch (nightly channel, Sonarr 5). On install it installs from develop. On update it switches the install to develop, so a Sonarr 4 install moves to Sonarr 5 | |
--4k | Install a dedicated 4K instance (Sonarr4K) with its own config and port | |
--v4 | Retired v3 to v4 flag. Do not use it: it is ignored, or the update stops with the error and changes nothing |
--4k is a flag on the base Sonarr package — it installs a dedicated Sonarr4K instance with its own port, install directory (/), configuration (~/), and quality profiles, so your standard and 4K libraries never conflict. There is no separate sonarr4k install command — you pass --4k to qb install sonarr. In the Dashboard, Sonarr4K appears as its own catalog entry you can install the same way.
When you run qb update sonarr -u username, QuickBox reads your current branch (main or develop) from config. and updates on it. You don’t need --nightly unless you want to switch to the nightly channel, and there is no CLI flag that switches back to stable: use the dashboard channel control, covered in Move to Sonarr 5.
Full flag reference: CLI Reference.
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/ Sonarr4 K/ - Config directory:
~/.config/ Sonarr4 K/ - Database:
~/.config/ Sonarr4 K/ sonarr. db - Service:
sonarr4k@username.service - Ports: Auto-generated (typically
8990+)
Move to Sonarr 5
Sonarr 5 is published on Sonarr’s develop branch, which QuickBox calls the Nightly channel. The stable channel (main) stays on Sonarr 4. To move a Sonarr 4 install to Sonarr 5, switch it to Nightly and update once.
Sonarr 5 is a new major version, and an update will not move an install back to Sonarr 4 afterwards (see Going back to stable). A Full Backup saves the install tree and a consistent copy of sonarr., and a Rollback puts both back. See Back up and restore.
From the dashboard
The channel control is available to admins.
- Open the App Dashboard and stay on Application Control.
- On the Sonarr row, find the version number. Click the small branch icon beside it (its tooltip reads Change release channel).
- In the Sonarr — Channel Settings dialog, choose Nightly.
- Click Save Channel. Saving writes the channel into Sonarr’s
config..xml - Run the update: click the amber Update badge when it appears on the Sonarr row (that dialog also has a channel picker and a Switch & Update Now button), or run the CLI command below.
The same control moves Sonarr4K: use the Sonarr4K row.
From the CLI
qb update sonarr -u username --nightlyThis switches the install to the develop branch and updates it in one step, so a Sonarr 4 install lands on Sonarr 5. For Sonarr4K add --4k. After the switch, a plain qb update sonarr -u username keeps updating on develop.
What QuickBox does after the move
- QuickBox follows the major you run. An install on Sonarr 5 is checked for and updated with Sonarr 5 releases. An install on Sonarr 4 stays on 4 until you choose Nightly.
- Sonarr can update itself. If you update from inside Sonarr, QuickBox keeps following the version you are on and never offers an older one.
- A new install on Nightly gets Sonarr 5 directly.
qb install sonarr -u username --nightlyinstalls fromdevelop.
Going back to stable
An update never installs a lower major than the one you run. If you set the channel back to Stable (on Nightly, click the amber channel badge in the Version column instead of the branch icon) and update a Sonarr 5 install, the update stops, changes nothing and reports that the newest release on the main branch is older than the version you run. Sonarr keeps running on Sonarr 5. To stay on Sonarr 5, set the channel back to Nightly. A reinstall without --nightly starts fresh on Stable (Sonarr 4) and deletes the config folder, so add --nightly to reinstall on Nightly. To get back to Sonarr 4, roll back to a Full Backup taken before the move (it holds the install tree and the config folder, see Back up and restore). If the Version column still shows Nightly after the rollback, set the channel back to Stable with Save Channel.
Sign in after the move
A QuickBox update never sets or changes an app login. When Sonarr 5 starts without a login user, it creates one itself: the user sonarr with a random password that it writes only to its log. Look for the line containing created 'sonarr' with the password in / (Sonarr4K: the logs folder under /).
Sign in with that user and password, then choose your own. Run qb user apppasswd -s sonarr -u username -o set to set a password: it replaces the generated sonarr login with your QuickBox username. You can also change it inside Sonarr under Settings → General → Security. We recommend keeping Sonarr’s own login on, with Authentication Method set to Forms and Authentication Required set to Enabled. An install that already had its own login keeps it through the update.
Legacy: Sonarr v3 to v4 (archived)
Accessing Sonarr
After installation, Sonarr is accessible through QuickBox’s nginx reverse proxy with SSL:
| Instance Type | Access URL |
|---|---|
| Standard | https://your-server-ip/username/sonarr |
| 4K Instance | https://your-server-ip/username/sonarr4k |
Sonarr is automatically integrated into your QuickBox dashboard. Find it on the App Dashboard (the default control view), stay on Application Control and expand its row for port and status. The API & Secrets section shows the Sonarr API key masked, with buttons to reveal it and copy it. Click Open to launch the web interface.
To install, reinstall, and remove applications, use the Package Management tab instead.
Network Configuration
QuickBox automatically configures:
- URL Base:
/(orusername/ sonarr /)username/ sonarr4k - Bind Address:
127.(local only - proxied through nginx)0. 0. 1 - Port: Auto-assigned (typically
8989for standard,8990+for 4K) - SSL: Handled by nginx reverse proxy (port 443)
- Authentication: Forms login with your QuickBox username and password, set by install and reinstall
Initial Configuration
1. Check the Sonarr login
An install or reinstall turns Sonarr’s own login on for you: Forms authentication with Authentication Required enabled, using your QuickBox username and password (or the password you set with qb user apppasswd -s sonarr -u username -o set). An update never changes it. If Sonarr is accessible from the internet, keep that login on.
To change it, go to Settings → General → Security inside Sonarr. Keep Authentication Method on Forms and Authentication Required on Enabled, and use a strong password. After a move to Sonarr 5, see Sign in after the move.
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
Configure categories in your download client (e.g., tv-) 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: Copy it from Sonarr’s row on the App Dashboard (API & Secrets section), or find it 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- 4 K
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)
Set upgrade cutoffs to prevent endless upgrading. For example, setting cutoff to Bluray- 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:
| Setting | Recommended Configuration |
|---|---|
| Rename Episodes | ✓ Enabled - Ensures consistent naming across your library |
| Replace Illegal Characters | ✓ Enabled - Removes filesystem-incompatible characters |
| Standard Episode Format | {Series Title} - S{season:00}E{episode:00} - {Episode Title} {Quality Full} |
| Daily Episode Format | {Series Title} - {Air-Date} - {Episode Title} {Quality Full} |
| Anime Episode Format | {Series Title} - S{season:00}E{episode:00} - {absolute:000} - {Episode Title} {Quality Full} |
| Series Folder Format | {Series Title} ({Series Year}) |
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
| Monitoring Option | Behavior |
|---|---|
| All Episodes | Monitor and download all episodes (past and future) - ideal for completing a full series |
| Future Episodes | Only monitor new episodes from now on - perfect for ongoing shows you're caught up on |
| Missing Episodes | Download missing episodes from existing seasons - useful for filling gaps |
| Existing Episodes | Don't search for old episodes - monitors only what you already have |
| First Season | Only monitor season 1 - great for testing new shows |
| Latest Season | Only monitor the most recent season - conserve bandwidth on long-running shows |
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
| Command | Description |
|---|---|
| systemctl status sonarr@username | Check service status and health |
| systemctl restart sonarr@username | Restart the service |
| systemctl stop sonarr@username | Stop the service |
| systemctl start sonarr@username | Start the service |
| journalctl -u sonarr@username -f | View live logs (follow mode) |
| journalctl -u sonarr@username --since today | View logs from today |
4K instance commands:
Replace sonarr with sonarr4k in all commands above:
systemctl status sonarr4k@username
systemctl restart sonarr4k@username
journalctl -u sonarr4k@username -fQuickBox automatically enables Sonarr to start on boot. You don’t need to run systemctl enable manually unless you’ve previously disabled it.
Back up and restore
QuickBox backs Sonarr up for you from the dashboard or the CLI, and the app keeps running while it does. Every backup is saved to /, named with the version and the date. For the 4K instance, replace sonarr with sonarr4k and Sonarr with Sonarr4 in the paths and commands below.
| Backup | What it saves |
|---|---|
| Config Only | config., the small configuration file. Your library, series and history are in the database, so use Full Backup for them |
| Full Backup | Two archives: sonarr-<version>-config_<date>.tar. holds your config folder / (the sonarr. database, taken as a consistent copy, plus config.), and sonarr-<version>-application_<date>.tar. holds the install tree /. The logs, Media (poster cache), Backups and Update folders are left out |
| Nginx | Sonarr’s nginx config, username. |
From the dashboard: open the App Dashboard, stay on Application Control, expand the Sonarr row and open Operations. Backup offers Full backup, Config Only and Nginx Only, and Restore lists every saved backup; for a full backup its button reads Rollback and puts back both the install tree and the config archive. Restore appears only when your account is allowed to restore backups. You can also open Content → Asset Management Center (AMC in the sidebar), choose the Application Backups tab, expand the Sonarr row and click Back up now; that row lists every saved file with download and delete buttons. See App Management → Application Backups for who can see the tab.
From the CLI:
# Config Only: config.xml
qb manage software -o backup -u username -s sonarr
# Full Backup: config folder with the database, plus the install tree
qb manage software -o backup -o app -u username -s sonarr
# Roll back to a Full Backup: pick the version from a menu, then confirm
qb manage software -o rollback -o app -u username -s sonarrEvery option is described in the qb manage reference.
A rollback stops Sonarr, clears the stale -wal, -shm and -journal files beside each restored database, puts the archives back, and starts Sonarr again. If Sonarr was running before the rollback, it also waits for Sonarr to answer on its port, and if it does not come back the command reports an error instead of finishing quietly.
qb remove sonarr and qb reinstall sonarr both delete / (the database and settings) and the backup folder / with every backup in it, and clear the rollback list. Before either one, download the Full Backup from the Application Backups tab, or copy the folder somewhere QuickBox does not manage:
cp -a /home/username/.QuickBox/software/sonarr/backup /home/username/sonarr-backup-savedRestore your library after a reinstall
Because the rollback list is cleared, a Full Backup you saved before a reinstall cannot be rolled back from the dashboard afterwards. Put back the database only and keep the new config., which matches the nginx config QuickBox just wrote. First stop Sonarr from its row in the App Dashboard with the Stop Sonarr button. Then run the file commands as your own account, and start Sonarr again with the Start Sonarr button. An admin with shell access can stop and start it with sudo systemctl stop sonarr@username and sudo systemctl start sonarr@username instead.
rm -f /home/username/.config/Sonarr/sonarr.db-wal /home/username/.config/Sonarr/sonarr.db-shm
tar -xzf /home/username/sonarr-backup-saved/sonarr-<version>-config_<date>.tar.gz -C /home/username/.config/Sonarr ./sonarr.dbRemoving the two -wal/-shm files first stops the new install’s journal from being applied to the restored database.
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 - Roll back to your last Full Backup if the database is corrupted (Back up and restore)
- 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/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
- Roll back to your last Full Backup: App Dashboard, expand the Sonarr row, Operations, Restore, then Rollback (or the CLI command in Back up and restore)
- No Full Backup yet? Restore Sonarr's own backup from System, Backup inside Sonarr (the zips in
~/).config/ Sonarr/ Backups - Last resort: stop the service with
systemctl stop sonarr@username, copy the damagedsonarr.somewhere safe, delete it and reconfigure from scratchdb - Do not reinstall to repair the database:
qb reinstall sonarrdeletes the config folder, database included
Check database integrity (stop the service first with systemctl stop sonarr@username):
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
*arrapps - 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
- Take a Full Backup before every update, upgrade or reinstall, and download a copy from the Application Backups tab in the Asset Management Center (Back up and restore)
- Use download client categories (e.g.,
tv-) to separate Sonarr downloadssonarr - 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 skip Full Backups, because corruption can happen and a reinstall or remove deletes the database and the backup folder with it
- Don't use Jackett if Prowlarr is available—Prowlarr is the modern replacement
Related Applications
Sonarr integrates seamlessly with the QuickBox ecosystem:
Additional Resources
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.
- Dedicated Support
- Feature Previews
- Community Configs
- Active Discussions