Why Subtitle Management Becomes a Problem Worth Solving
Anyone who runs a home media server knows the subtitle situation eventually becomes unmanageable. You download a film, fire it up, and either the subtitle file is missing entirely, named incorrectly so your player ignores it, or synced so badly that the dialogue runs three seconds ahead of the mouths on screen. Multiply that across hundreds of titles and dozens of languages, and manually hunting down SRT files becomes a part-time job nobody signed up for.
Bazarr is an open-source companion application designed to sit alongside Sonarr and Radarr and handle subtitle retrieval automatically. It monitors your media libraries, detects missing subtitles, queries providers like OpenSubtitles and Subscene, downloads matches, and drops the files exactly where your media player expects them. Once it is running, the subtitle gap closes itself. This guide walks through the full setup process from installation to first automated download.
Prerequisites and Installation
Bazarr runs on Windows, macOS, Linux, and inside Docker. For most home server setups, Docker is the cleanest path because it keeps dependencies isolated and makes updates trivial. You will need Docker and Docker Compose already installed on your host machine, along with Sonarr or Radarr pointing at your media directories – Bazarr reads from those libraries rather than managing its own. Your media folder structure should be consistent, since Bazarr maps its paths against whatever Sonarr and Radarr already know.
Create a directory for Bazarr’s configuration files, then add the following to a docker-compose.yml file. Use the lscr.io/linuxserver/bazarr image, set PUID and PGID to match your host user, define TZ for your timezone, map port 6767 to the host, mount your config directory to /config inside the container, and mount your movies and TV folders using the same paths Sonarr and Radarr use. That last point matters more than most people expect – if Sonarr sees your media at /media/tv, Bazarr must see it at the same path, otherwise the path-matching between the two applications breaks and Bazarr cannot place downloaded subtitle files correctly. Run docker compose up -d and the container starts in the background.
Configuring the Web Interface
Open a browser and navigate to http://your-server-ip:6767. The first-run wizard walks through the core settings. Under Settings > General, set your base URL if you are running Bazarr behind a reverse proxy – leave it blank otherwise. The interface language and logging level can stay at defaults for now.
The Sonarr and Radarr integration panels are under Settings > Sonarr and Settings > Radarr. Toggle each one on, enter the local IP and port of each service, then paste in the API key from that service’s settings page. Hit the Test button – a green confirmation message means Bazarr can read the library. If the test fails, double-check that both containers are on the same Docker network, or that the IP address is reachable from wherever Bazarr is running. Once both connections are confirmed, Bazarr pulls in your full library list, which can take a few minutes on large collections.
Language profiles are the heart of how Bazarr decides what to download. Navigate to Settings > Languages and create a profile. Give it a name, add your desired languages in priority order, and choose whether each language should be treated as a required download or a preferred one. The distinction controls behavior: required languages block a title from being considered “complete” until that subtitle exists; preferred languages get downloaded when available but do not hold up the queue. You can also enable Forced subtitles as a separate track if you want foreign-language dialogue lines subtitled even when the main subtitle is off.
Assign your profile to Sonarr and Radarr libraries by going back to each integration panel and selecting the profile from the dropdown. You can also set per-series or per-movie overrides later directly from the library views, which is useful for foreign-language content that needs a different language priority than everything else in your collection.
Adding Subtitle Providers
Bazarr supports a range of subtitle providers, each with different coverage strengths. Under Settings > Providers, enable the ones you want. OpenSubtitles is the most commonly used and covers the broadest range of languages, but requires a free account registration to get API access – unauthenticated requests are rate-limited to the point of being nearly useless. OpenSubtitles.com (the newer platform, distinct from the older .org API) has its own separate credentials, so if you have accounts on both, both are worth enabling. Addic7ed has strong coverage for English-language TV series. Subscene covers non-English content well. Enable multiple providers and Bazarr queries them in sequence, stopping once it finds a match that meets your scoring threshold.
The scoring system under Settings > Subtitles controls how strict the match needs to be before a download is accepted. Score is calculated based on how closely the subtitle file matches the specific release – matching on series, season, episode, release group, and codec all contribute points. Setting the minimum score too low means you accept subtitles synced to a different encode, which causes timing drift. Setting it too high means Bazarr finds nothing for niche releases. A minimum around 90 out of 120 works well for most libraries, but lower it per-provider if you are finding too many titles going unmatched.
Running the First Scan and Ongoing Automation
After saving provider settings, go to System > Tasks and manually trigger the Search for Missing Subtitles job. Bazarr scans every title in your linked libraries, checks for existing subtitle files, and queues downloads for anything missing according to your language profiles. On a large library the first run can take an hour or more – this is normal. You can watch download activity in real time under the History tab.
Going forward, Bazarr handles new additions automatically. When Sonarr or Radarr grabs a new file, it sends a webhook notification to Bazarr, which immediately searches for subtitles on that title rather than waiting for the next scheduled scan. Set the webhook URL in Sonarr under Settings > Connect > Add Connection > Bazarr using http://bazarr-ip:6767/api/webhooks/sonarr – the Radarr equivalent follows the same pattern. Without this webhook, new downloads get subtitles only on the next scheduled task run, which by default runs every few hours.
If you want Bazarr accessible from outside your home network without opening ports, pairing it with a Cloudflare Tunnel gives you encrypted remote access without exposing your server directly. Back inside Bazarr, the Wanted tab shows every title still missing subtitles after the initial scan – anything sitting there is either a very niche release with no available subtitle file yet, or a scoring mismatch worth investigating. Clicking into an individual title lets you manually trigger a search with relaxed scoring, or even paste in a custom subtitle file if you sourced one elsewhere.
