Bazarr
Automated subtitle management for Sonarr and Radarr
Bazarr is a companion application to Sonarr and Radarr. It manages and downloads subtitles based on your requirements. You define your preferences by TV show or movie and Bazarr takes care of everything for you—from downloading to syncing and organizing subtitles automatically.
🔍 Automatic Subtitle Search
Automatically search for and download subtitles for your TV shows and movies from multiple providers
🌐 Multi-Provider Support
Supports OpenSubtitles, Subscene, Addic7ed, Podnapisi, and many more subtitle providers
📺 Sonarr & Radarr Integration
Seamless integration with Sonarr and Radarr for automatic subtitle management of your entire library
🎯 Language Profiles
Configure language preferences per show/movie with fallback options and forced subtitle support
⚙️ Sync & Timing Adjustment
Automatic subtitle synchronization and timing correction using ffsubsync for perfect alignment
📊 Manual Search
Manual search interface for finding and downloading specific subtitle versions when needed
Installation
Symptoms
- QuickBox Pro v3 installed and configured
- Sonarr and/or Radarr installed and configured
- TV shows and movies need subtitles
- User account created on the server
Resolution
- Use QuickBox's qb command for installation
- Automatic Python 3.11 virtual environment setup
- Configurable subtitle language preferences
- Per-user installation with isolated configurations
Basic Installation
Install Bazarr for a specific user:
qb install bazarr -u usernamePython Virtual Environment
QuickBox Pro automatically creates a Python 3.11 virtual environment for Bazarr with all required dependencies (pip, idna, pylzma, py7zr, apprise). This ensures compatibility and isolation from system Python packages.
Installation Variants & CLI Commands
| Command | Description |
|---|---|
qb install bazarr -u username | Install standard Bazarr instance with automatic configuration |
qb install bazarr -u username --4k | Install separate 4K instance for high-resolution content |
qb reinstall bazarr -u username | Reinstall Bazarr (preserves configuration and database) |
qb update bazarr -u username | Update to latest version |
qb remove bazarr -u username | Remove standard installation |
qb remove bazarr -u username --4k | Remove 4K instance |
qb help bazarr | Display comprehensive help information |
4K Instance
The --4k flag creates a separate Bazarr4K instance dedicated to managing subtitles for 4K/UHD content with its own port, configuration (/username/bazarr4k), and language profiles—perfect for managing standard and 4K subtitle workflows separately.
Accessing Bazarr
After installation, access Bazarr at:
Standard installation:
https://your-server-ip/username/bazarr4K instance:
https://your-server-ip/username/bazarr4kQuickBox Dashboard Integration
Bazarr is automatically integrated into your QuickBox dashboard. Find it in the Service Control panel with port and status information. Click the LAUNCH icon to open the web interface.
Initial Configuration
1. Connect to Sonarr & Radarr
Link Bazarr to your *arr apps for automatic subtitle management:
Sonarr:
- Settings → Sonarr
- Click Add Sonarr (+)
- Enter connection details:
- Address:
http://localhost:8989 - API Key: Copy from Sonarr (Settings → General → Security → API Key)
- URL Base:
/username/sonarr
- Address:
- Test connection and save
Radarr:
- Settings → Radarr
- Click Add Radarr (+)
- Enter connection details:
- Address:
http://localhost:7878 - API Key: Copy from Radarr (Settings → General → Security → API Key)
- URL Base:
/username/radarr
- Address:
- Test connection and save
Automatic Library Sync
Once connected, Bazarr automatically syncs your TV shows and movies from Sonarr/Radarr. This sync runs periodically and can be manually triggered from the Settings page.
2. Configure Subtitle Providers
Add subtitle providers for downloading:
- Settings → Providers
- Click Add Provider (+)
- Select provider (OpenSubtitles, Subscene, etc.)
- Enter credentials (if required)
- Set provider priority
Popular Providers:
- OpenSubtitles - Large database, requires free account
- Subscene - Quality subtitles, no account needed
- Addic7ed - Excellent for TV shows, requires account
- Podnapisi - Good coverage, no account needed
3. Set Language Profiles
Configure subtitle language preferences:
- Settings → Languages
- Create language profile
- Select desired languages
- Set fallback languages (optional)
- Configure forced subtitle options
Example Profile:
- Primary: English
- Secondary: English (Forced)
- Fallback: Spanish
4. Enable Automatic Search
Configure automatic subtitle downloads:
- Settings → Sonarr/Radarr
- Enable Download Only Monitored
- Set Automatic Search:
- When episode/movie is added
- When episode/movie is upgraded
- On schedule (every X hours)
Service Management
Bazarr runs as a systemd service for reliability and automatic startup.
Standard installation:
systemctl status bazarr@username # Check status
systemctl restart bazarr@username # Restart service
journalctl -u bazarr@username -f # View live logs
systemctl enable bazarr@username # Start on boot
systemctl disable bazarr@username # Prevent auto-start4K instance:
systemctl status bazarr4k@username
systemctl restart bazarr4k@username
journalctl -u bazarr4k@username -fTroubleshooting
Bazarr Won’t Start
journalctl -u bazarr@username -fCheck for port conflicts:
grep 'port:' ~/.config/Bazarr/config/config.yaml
# Default: 6700Subtitles Not Downloading
Symptoms
- No subtitles found in manual search
- Automatic downloads not working
- Provider connection errors
- Shows/movies synced but no subtitles appear
Resolution
- Verify providers are working: Settings → Providers → Test
- Check Sonarr/Radarr connection: Settings → Sonarr/Radarr → Test
- Ensure language profiles are configured correctly
- Try manual search: Series/Movie → Manual Search icon
Provider Rate Limiting
# Check provider status
# Settings → Providers → View provider stats
# Adjust rate limits per provider
# Edit Provider → Advanced → Rate LimitPermission Issues
qb fix permissions -u username
systemctl restart bazarr@usernamePython Virtual Environment Issues
# Verify virtual environment exists
ls -la /opt/username/lib/python/Bazarr/.venv
# Reinstall to recreate venv
qb reinstall bazarr -u usernameBest Practices
Do
- Install Sonarr/Radarr before Bazarr for seamless integration
- Configure multiple subtitle providers for better coverage
- Use language profiles to define subtitle preferences per show/movie
- Enable automatic search for hands-free subtitle management
- Set up subtitle sync for improved timing accuracy
- Use separate 4K instance for managing 4K subtitle workflows
- Monitor provider statistics to identify underperforming sources
- Keep Bazarr updated via qb update bazarr for latest features
Don't
- Don't use too many providers—causes rate limits and slow searches
- Don't ignore provider rate limit warnings—can result in bans
- Don't forget to test providers after adding them
- Don't mix standard and 4K subtitle workflows—use separate 4K instance
- Don't disable authentication if Bazarr is accessible from the internet
- Don't manually edit config files—use the web interface
- Don't forget to configure language profiles before enabling automatic search
- Don't ignore failed download warnings—investigate provider issues
Use Cases
Automated Subtitle Management
- Automatically download subtitles for new TV episodes as they’re added
- Fetch subtitles for movies when they’re grabbed by Radarr
- Keep subtitle library up-to-date without manual intervention
Multi-Language Support
- Download subtitles in multiple languages for international households
- Configure fallback languages for shows without primary subtitle availability
- Manage forced subtitles for foreign language scenes
Quality Control
- Use manual search to find higher quality subtitle versions
- Replace poor subtitles with better alternatives from different providers
- Sync subtitles with video timing for perfect alignment
Related Applications
Additional Resources
Join the Community
Media server operators sharing configs, getting support, and shaping the future of QuickBox Pro.