Automate Subtitle Downloads for Plex with Bazarr
Published 2026-10-16 · PlexBeam
Bazarr is a companion application that automatically downloads subtitles for every movie and TV show in your Plex library. It monitors your Sonarr and Radarr libraries, checks multiple subtitle providers for the best available subtitles, downloads them, and places them alongside your media files where Plex picks them up automatically. Without Bazarr, finding subtitles means manually searching OpenSubtitles or Subscene for every title — tedious for a small library and impossible for a large one.
How Bazarr works
Bazarr integrates with your existing media management stack:
- Connection to Sonarr and Radarr: Bazarr reads your media library from Sonarr (TV shows) and Radarr (movies) rather than scanning the filesystem directly. This gives Bazarr accurate metadata — the correct title, year, season, and episode number — which is critical for finding matching subtitles. If you do not use Sonarr or Radarr, Bazarr can still work but requires manual configuration of media paths
- Subtitle providers: Bazarr searches multiple subtitle sources simultaneously — OpenSubtitles.com, Addic7ed, Podnapisi, Subscene, and others. Each provider specializes in different content. OpenSubtitles has the largest database. Addic7ed excels at TV shows. Podnapisi covers European languages well. Using multiple providers maximizes the chance of finding subtitles for every title
- Automatic matching: Bazarr matches subtitles by release group, video codec, resolution, and hash when possible. A subtitle matched by video hash is almost always synchronized correctly. When hash matching is not available, Bazarr falls back to matching by title, year, and release name, which works well but occasionally results in timing mismatches
- Scheduled checks: Bazarr runs on a configurable schedule — checking for missing subtitles every few hours or once daily. When new media appears in Sonarr or Radarr, Bazarr detects it and immediately searches for subtitles. Missing subtitles are retried on each scheduled run until found
Installation
Docker is the recommended installation method for Bazarr, especially if you already run Sonarr and Radarr in Docker:
- Docker Compose: Add Bazarr to your existing Docker Compose stack. Use the
linuxserver/bazarrimage. Mount your media directories (movies and TV shows) so Bazarr can place subtitle files alongside the video files. Mount a config volume to persist settings between container updates. Set environment variables for PUID, PGID, and TZ to match your other containers - Port: Bazarr's web interface runs on port 6767 by default. Map this port in your Docker Compose or change it to avoid conflicts with other services. Access the web interface at
http://your-server-ip:6767after starting the container - Bare metal installation: On Linux, install Python 3.8+ and clone the Bazarr repository. Run with
python3 bazarr.py. On Windows, download the release ZIP and runbazarr.exe. The Docker method is preferred because it handles dependencies and updates cleanly - First-run wizard: On first access, Bazarr presents a setup wizard. Configure your subtitle languages, connect to Sonarr and Radarr, add subtitle providers, and set your preferences. The wizard covers all essential settings — take time to configure it properly rather than accepting defaults
Configuring subtitle providers
Providers are the sources Bazarr searches for subtitles. Configure multiple providers for best coverage:
- OpenSubtitles.com: The largest subtitle database. Create a free account at opensubtitles.com and add your credentials to Bazarr. The free tier allows 20 downloads per day — sufficient for maintaining an established library. The VIP tier ($3/month) removes limits and provides faster downloads. Required for most libraries
- Addic7ed: Excellent for TV shows, especially current airing series. Create a free account at addic7ed.com. Addic7ed subtitles are often available within hours of a show airing. The site limits downloads for free users — a VIP account removes the limit
- Podnapisi: Good coverage for European languages and older content. No account required. Podnapisi is a free, community-maintained subtitle database
- Embedded subtitles extractor: Bazarr can extract subtitles embedded in MKV files and save them as external SRT files. This is useful when you prefer external subtitle files for compatibility with certain Plex clients. Enable the embedded subtitles provider in Bazarr settings
- Provider priority: Order providers by quality in Bazarr settings. Put your most reliable provider first. Bazarr searches providers in order and uses the first match that meets your quality criteria. If the first provider returns a poor match, Bazarr tries the next
Language profiles
Language profiles tell Bazarr which subtitle languages to download for different content:
- Default profile: Set your primary language as the default. For most English-speaking users, this means downloading English subtitles for everything. If your household speaks multiple languages, create a profile that downloads subtitles in all needed languages
- Hearing impaired subtitles: Configure whether to prefer hearing-impaired subtitles (which include sound descriptions like [door slams] and [music playing]) or standard subtitles. Some users prefer hearing-impaired subtitles for the additional context even if they do not have hearing difficulties
- Forced subtitles: Forced subtitles display only for foreign-language dialogue in an otherwise English-language film — the alien language in a sci-fi movie, for example. Enable forced subtitle searching for your primary language. Bazarr searches for forced subtitles separately from full subtitles
- Per-series profiles: Assign different language profiles to specific shows or movies. An anime series might need Japanese and English subtitles while a French film needs only English. Bazarr allows per-title profile overrides in its interface
Sonarr and Radarr integration
Connecting Bazarr to Sonarr and Radarr is essential for accurate subtitle matching:
- API connection: In Bazarr settings, add your Sonarr and Radarr instances with their URL and API key. Find the API key in Sonarr or Radarr under Settings, General. Bazarr syncs your library metadata from these services and uses it to search for subtitles accurately
- Path mapping: If Bazarr, Sonarr, and Radarr run in separate Docker containers, the media paths they see may differ. Configure path mapping in Bazarr so it knows where files actually exist on disk. Example: Sonarr sees
/tvbut the actual host path is/mnt/media/tv. Set the path mapping accordingly - Sync interval: Bazarr syncs with Sonarr and Radarr every few hours by default. Reduce the interval if you want subtitles to appear faster after new media downloads. Increasing the interval reduces API calls if your server is resource-constrained
Subtitle quality and synchronization
- Score threshold: Bazarr assigns a score to each subtitle based on how well it matches the video — hash match, release group match, resolution match, and codec match. Set a minimum score threshold to avoid downloading poorly matched subtitles. A threshold of 90+ ensures good matches. Lower thresholds (60-70) find more subtitles but risk sync issues
- Automatic sync correction: Bazarr includes built-in subtitle synchronization that adjusts timing offsets automatically. Enable this in settings — it uses audio analysis to align subtitle timing with the actual dialogue in the video file. This fixes the most common subtitle problem: subtitles that are a few seconds early or late
- Post-processing: Bazarr can remove hearing-impaired tags from standard subtitles, convert subtitle formats (ASS to SRT), and fix common encoding issues. Enable these post-processing options to deliver clean, consistent subtitles to Plex
- Manual search: When automatic search fails to find subtitles, use Bazarr's manual search to browse all available subtitles from all providers. You can preview subtitle content before downloading to verify it matches your release
Troubleshooting common issues
- Subtitles not appearing in Plex: Verify that the subtitle file is in the same directory as the video file and follows Plex's naming convention:
Movie (2024).en.srtfor English subtitles. Refresh the Plex library after Bazarr downloads new subtitles. Enable the Plex notification agent in Bazarr to trigger automatic refreshes - Wrong subtitles downloaded: Increase the score threshold in Bazarr settings. Enable hash-based matching if available from your providers. If a specific title consistently gets wrong subtitles, blacklist the bad subtitle in Bazarr and trigger a new search
- Provider errors: If a provider shows errors in the Bazarr log, check your account credentials and verify the provider is not experiencing downtime. Free-tier rate limits on OpenSubtitles cause intermittent errors during heavy download periods — the daily limit resets at midnight UTC
- Sync timing off: Enable Bazarr's automatic synchronization feature. If subtitles are consistently offset for a specific release group, download subtitles from a different provider. The manual search interface lets you pick alternative subtitles when the automatic choice has timing issues