Bazarr: subtitle management for Sonarr and Radarr libraries

The gap Bazarr fills between Sonarr, Radarr and subtitle files

Sonarr and Radarr track series and movies, but neither of them fetches subtitles. That leaves a manual step after every import: open a subtitle site, search by release name, download the file, rename it to match the video, and drop it next to the media. Bazarr exists to remove that step. It is described in its README as a companion application to Sonarr and Radarr that manages and downloads subtitles based on your requirements, with preferences defined by TV show or movie.

The audience is people who already run the Sonarr and Radarr stack and want subtitle languages handled per title rather than globally. The README lists series- and movie-based subtitle language configuration as a feature, which matters if you watch some shows with forced foreign subtitles and others with full subtitles. The project supports 184 subtitle languages according to its feature list, so the language model is not limited to the common European set.

The most important sentence in the README is a boundary: Bazarr does not scan your disk to detect series and movies, and only manages what Sonarr and Radarr index. If your library lives outside those two applications, Bazarr has nothing to work with. That single design decision shapes everything else about how you deploy it.

How Bazarr decides what to download

Bazarr is a Python application. The repository root holds bazarr.py, and the application code sits in a bazarr/ package alongside custom_libs/ and libs/, with a frontend/ directory for the web UI and a migrations/ directory for database schema changes. The README credits the interface design to Sonarr, which is why the settings screens follow the same shape as the Sonarr and Radarr UIs.

The data flow is a chain of API calls rather than filesystem walks. Bazarr asks Sonarr and Radarr for the series, movies and episodes they already track, then checks each item against the subtitles it expects. For each missing subtitle it queries the enabled providers in the list, and the README names a long set: OpenSubtitles.com, Subscene, SubDL, Addic7ed, BSplayer, and regional sites such as Titlovi and Titrari.ro. A few entries are not remote services at all: Embedded Subtitles extracts tracks already inside your files, and Whisper requires a separate ahmetoner/whisper-asr-webservice instance for speech recognition. Subsarr and SubsDump are self-hosted providers that require their own repositories.

After a download, Bazarr keeps a history of what was downloaded, from where, and when, per the feature list. It can also upgrade a previously downloaded subtitle when a better one is found, and delete external subtitles from disk. The manual search screen lets you pull a subtitle on demand when the automatic pass picks the wrong release.

Installing Bazarr and running a first subtitle search

The README does not include installation commands; it points to the wiki at wiki.bazarr.media for documentation, and to Docker Hub images published by linuxserver and hotio. The Docker route is the one the project surfaces first, through those image links.

If you run Bazarr from the repository directly, the dependencies are listed in requirements.txt. Installing them is the first step before launching the application.

pip install -r requirements.txt

That file pins lxml at 4.3.0 or newer, numpy at 1.12.0 or newer but below 2.4.0, webrtcvad-wheels at 2.0.10 or newer, and Pillow at 9.0.0 or newer, with pywin32 added on Windows. The numpy ceiling is annotated in the file as a guard against a segfault on older hardware caused by CPU requirements introduced in numpy 2.4.0.

The application entry point is bazarr.py at the repository root. Running it starts the service and its web UI.

python bazarr.py

The first real task after that is connecting Sonarr and Radarr. In the Bazarr settings you enter the host, port and API key for each. Bazarr then imports the series and movies those applications already track. Nothing appears in Bazarr that Sonarr and Radarr do not know about, so an empty list usually means a wrong API key or an unreachable host rather than a missing library.

After the connection works, enable at least one provider and set a language profile. A manual search on a single episode is the fastest way to confirm the whole chain: the provider responds, the subtitle lands next to the video file, and the history entry records it.

Where Bazarr breaks down

Provider availability is the sharpest limitation. The README lists dozens of providers, but several entries carry conditions that are easy to miss. OpenSubtitles.org is marked VIP users only. Animetosho requires an AniDb HTTP API client. AvistaZ and CinemaZ require session cookies obtained by a method described in a pull request comment. Ktuvit requires a hashed_password generated by an external tool. Whisper, Subsarr and SubsDump each require a separate service the reader has to run. If you enable a provider without meeting its condition, you get failures rather than subtitles, and the README does not document rollback or a retry policy for those cases.

The second limitation is the indexing boundary again. Because Bazarr never scans disk, a media file that Sonarr or Radarr has not imported is invisible to it, even if the file sits in the same folder as indexed items. People who curate a library by hand, or who use a different media manager, will find Bazarr silent.

The third is subtitle quality. Bazarr can upgrade a subtitle when a better one is found, but the definition of better comes from the provider and the scoring rules, not from a frame-accurate sync check. A downloaded subtitle can still be out of sync with a specific release, and the fix is a manual search rather than an automatic correction. Whisper is the exception in principle, since it transcribes audio, but it needs that separate ASR service and the compute to run it.

Bazarr compared with running Subliminal or a media server plugin

Subliminal is the older approach and appears in Bazarr's own topic list. It is a command line tool that you point at a folder or a file, and it searches providers for that specific path. The difference is the source of truth. Subliminal starts from the filesystem, so it works on any library regardless of how it was assembled. Bazarr starts from the Sonarr and Radarr databases, so it knows language preferences per series and per movie and can react when a new episode is imported. If you want subtitle automation without running Sonarr and Radarr, Subliminal is the more direct fit. If you already run both, Bazarr's per-title language configuration is something a folder-based tool cannot express.

Media server plugins are the other comparison point. Plex and Jellyfin can fetch subtitles through their own agents, and search traffic shows people asking how to use Bazarr with Plex and with Jellyfin. Those built-in agents operate inside the server and typically apply one language setting across the library. Bazarr sits outside the server, writes subtitle files next to the video, and keeps a history. The trade-off is an extra service to run and a dependency on Sonarr and Radarr being correct. If your library is small and a single subtitle language is enough, the server's own agent is less machinery.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-23. The release list shows v1.6.2-beta.5 published that same day, with v1.6.2-beta.4 and v1.6.2-beta.3 on the two days before, so the release cadence at this moment is beta builds rather than a stable tag. Anyone deploying Bazarr should decide whether to track beta images or pin a stable version, because the recent releases listed are all betas.

Upgrade cost is mostly the provider layer. Providers change their sites, add authentication requirements or disappear, and the README already documents several that need manual credential extraction. A Bazarr upgrade can therefore require re-reading provider notes rather than just restarting a container. The application also carries a migrations/ directory, which implies database schema changes across versions; back up the config volume before a major jump.

Bazarr is licensed under GNU GPL v3, with copyright stated as 2010-2026. That is a copyleft licence. If you run Bazarr as a service for your own media, the practical effect is minimal. If you intend to modify and distribute it, or to bundle it into a product, the GPL obligations apply to the distributed work. This is a description of the licence, not legal advice; consult a lawyer for your specific case.

Editorial conclusion

Adopt Bazarr if your media is already indexed in Sonarr and Radarr and you want per-series and per-movie subtitle languages handled without manual searches. Skip it if you keep a library outside those tools, since the README states Bazarr does not scan your disk and only manages what Sonarr and Radarr index. Before committing, verify that Sonarr and Radarr are reachable from the Bazarr host, that at least one provider account is configured, and that the language profile you want exists for the series or movie you are testing.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. morpheus65535/bazarr on GitHub
3. Project website
4. README
5. Releases