Bazarr serves as a critical companion application designed specifically to integrate with Sonarr and Radarr, providing a centralized management system for the automated acquisition and organization of subtitles. In a modern home media ecosystem, the ability to define specific preferences for movies and television series and have a dedicated agent handle the searching and downloading of subtitles is paramount for a seamless viewing experience. By leveraging Docker, users can isolate this application from the host operating system, ensuring consistent performance across various hardware architectures and simplifying the update process.
The deployment of Bazarr via Docker is not merely about starting a container; it involves a precise orchestration of network paths, volume mappings, and API integrations. When deployed correctly, Bazarr monitors your media libraries and automatically fetches subtitles based on predefined language requirements. However, the complexity arises when integrating these containers within a network, particularly when dealing with loopback addresses and path mappings between different services. This guide provides an exhaustive deep dive into the installation, configuration, and optimization of Bazarr using the most reputable Docker images available.
Docker Image Selection and Provenance
When deploying Bazarr, users typically choose between two primary maintainers: hotio and linuxserver. Both provide high-quality, frequently updated images, but they differ in their update cycles and tagging conventions.
The linuxserver image is highly regarded for its consistency and support for non-root users. It is available via the lscr.io registry. The available tags for this image include latest, which tracks stable releases from Bazarr, and development, which provides access to pre-releases for users who wish to test new features before they hit the stable branch.
Conversely, the hotio image offers a slightly different tagging structure, providing latest (equivalent to stable) and nightly builds. The hotio ecosystem is characterized by an aggressive update schedule, with application updates occurring every 30 minutes and upstream image updates every hour, ensuring that the latest bug fixes are deployed almost instantaneously.
The following table outlines the technical specifications and availability of the most common images:
| Maintainer | Image Name | Available Tags | Update Frequency | Config Path |
|---|---|---|---|---|
| linuxserver | lscr.io/linuxserver/bazarr |
latest, development | Regular/Timely | /config |
| hotio | hotio/bazarr |
latest, nightly, versioned (e.g., stable-0.8.3.4) | 30m (apps) / 1h (image) | /config |
Hardware Architecture and Compatibility
The linuxserver image is designed to be architecture-agnostic to a great extent. By pulling the latest tag, the Docker engine automatically retrieves the correct image for the host's CPU architecture. This is critical for users running a mix of x86-64 servers and ARM-based devices like the Raspberry Pi.
The supported architectures and their corresponding tags are as follows:
- x86-64: Available via
amd64-<version tag> - arm64: Available via
arm64v8-<version tag>
This architectural flexibility ensures that Bazarr can be deployed across a wide spectrum of hardware, from enterprise-grade rack servers to low-power single-board computers, provided the Docker runtime is correctly configured.
Detailed Deployment Methodology
Deployment can be achieved through two primary methods: the Docker Command Line Interface (CLI) or a Docker Compose YAML file. The latter is strongly recommended for long-term maintenance and readability.
Docker Compose Configuration
The Docker Compose method allows for the declarative definition of the container's environment, volumes, and network ports.
yaml
services:
bazarr:
image: lscr.io/linuxserver/bazarr:latest
container_name: bazarr
environment:
- PUID=1000
- PGID=1000
- TZ=Etc/UTC
volumes:
- /path/to/bazarr/config:/config
- /path/to/movies:/movies #optional
- /path/to/tv:/tv #optional
ports:
- 6767:6767
restart: unless-stopped
Docker CLI Execution
For those preferring a one-liner approach via the terminal, the following command is utilized:
bash
docker run -d \
--name=bazarr \
-e PUID=1000 \
-e PGID=1000 \
-e TZ=Etc/UTC \
-p 6767:6767 \
-v /path/to/bazarr/config:/config \
-v /path/to/movies:/movies \
-v /path/to/tv:/tv \
--restart unless-stopped \
lscr.io/linuxserver/bazarr:latest
Analysis of Runtime Parameters
Each parameter passed during the container startup serves a specific technical purpose:
-p 6767:6767: This maps the internal port 6767 of the Bazarr container to port 6767 on the host IP. This allows the user to access the web interface viahttp://<host-ip>:6767.-e PUID=1000: This specifies the User ID. Ensuring the PUID matches the user who owns the media files on the host prevents permission errors.-e PGID=1000: This specifies the Group ID, mirroring the PUID logic to maintain consistent group ownership.-e TZ=Etc/UTC: This sets the timezone for the container, which is essential for accurate logging and scheduled subtitle searches.-v /path/to/bazarr/config:/config: This mounts a host directory to the internal/configfolder. This is where all settings and the SQLite database are stored.
Critical Storage and Filesystem Constraints
A paramount technical requirement for Bazarr is the nature of its configuration storage. Bazarr utilizes SQLite for its database management. SQLite is fundamentally incompatible with NFS (Network File System) shares due to the way it handles file locking.
If a user attempts to store the /config directory on an NFS share, the application will trigger a "locked database error," leading to catastrophic failure of the application's ability to save settings or track subtitles. Consequently, the configuration directory must be stored on a local filesystem (such as EXT4 or XFS) or a block-level storage solution.
Additionally, the linuxserver image supports advanced filesystem operations, such as running the container with a read-only filesystem to enhance security, and running as a non-root user to adhere to the principle of least privilege.
Integration with Sonarr
Once the container is operational and the web interface is accessed at http://<host-ip>:6767, the first step is the integration with Sonarr. This connection allows Bazarr to know which TV shows are present and where they are located.
Connection Settings
To enable the integration, navigate to Settings => Sonarr and follow these steps:
- Enable Sonarr: Toggle the "Use Sonarr" option to "Enabled".
- Hostname/IP: Enter the IP address of the machine running Sonarr.
- TCP Port: The default port for Sonarr is
8989. - API Key: Enter the unique API key generated within the Sonarr settings.
- SSL: Enable this only if the Sonarr instance is accessed via HTTPS. This is not required for local IP connections.
The Loopback Address Pitfall
A critical technical nuance occurs when Bazarr and Sonarr are both running as Docker containers on the same host. Users must not use the loopback address (e.g., 127.0.0.1 or localhost). In a Docker environment, localhost refers to the interior of the Bazarr container itself, not the physical host or other containers. To connect to Sonarr, users must use the host's internal IP address or the container name if they are on the same Docker bridge network.
Sonarr Filtering and Exclusions
Bazarr provides granular control over which content receives subtitles based on Sonarr's data:
- Custom Tags: Users can add a custom tag to a show within Sonarr. Bazarr can be configured to ignore any show carrying these specific tags.
- Series Type Exclusion: Subtitle downloads can be disabled for specific series types. The available options for exclusion include
Standard,Anime, andDaily. - Monitoring Status: By default, Bazarr will only perform automatic subtitle downloads for shows and episodes that are marked as "Monitored" within Sonarr.
Integration with Radarr
The integration with Radarr follows a similar logic to Sonarr, as both applications serve as the source of truth for the media libraries.
Connection Parameters
Navigate to Settings => Radarr and configure the following:
- Enable Radarr: Toggle the "Use Radarr" option to "Enabled".
- Hostname/IP: Enter the IP address of the Radarr instance. Again, avoid
127.0.0.1when using Docker. - TCP Port: The default port for Radarr is
7878. - API Key: Enter the Radarr API key.
- SSL: Enable this if Radarr is exposed via SSL.
- Test Connection: Always click the "Test" button to verify that the API communication is successful before saving.
Reverse Proxy Configuration
For users who employ a reverse proxy (such as Nginx, Traefik, or HAProxy), the "URL Path" field becomes relevant. If Radarr is exposed via a path like /radarr, this exact path (including the leading slash) must be entered into the Bazarr settings. If no reverse proxy is used, this field must be left empty. Failure to leave this empty when not applicable may result in connection errors.
Path Mapping and Volume Synchronization
One of the most complex aspects of a Bazarr deployment is ensuring that the paths seen by Sonarr/Radarr match the paths seen by Bazarr.
The Necessity of Path Mappings
Path mappings are required only if Sonarr and Bazarr use different absolute paths to access the same physical files. Common scenarios requiring this include:
- Sonarr and Bazarr are running on different physical devices.
- A mix of native OS packages (e.g., Synology DSM packages) and Docker containers is used.
- Inconsistent volume mapping during the Docker setup.
Configuring Path Mappings
To implement this, click "Add" in the Path Mappings section. You will be presented with two fields:
- Sonarr/Radarr Path: The path the media manager uses (e.g.,
/data/media/tv). - Bazarr Path: The path Bazarr uses to access the same folder (e.g.,
/tv).
A critical warning is issued: if the paths are identical on both sides, path mapping must not be used. If identical values are entered, Bazarr will trigger an error. For those using Docker, the ideal solution is to ensure consistent paths across all containers (e.g., both using /data/media/tv) to avoid the need for mappings entirely. Users are encouraged to consult the TRaSH Hardlink Tutorial to achieve optimal path consistency.
Conclusion
The deployment of Bazarr via Docker transforms the subtitle management process from a manual chore into an automated background service. By selecting the appropriate image from linuxserver or hotio, users gain a stable environment that supports multiple architectures and non-root execution. The technical success of the installation hinges on three critical factors: the avoidance of NFS for configuration storage to prevent SQLite locking issues, the correct use of host IP addresses instead of loopback addresses for inter-container communication, and the precise alignment of path mappings between Bazarr and its companion applications, Sonarr and Radarr.
When these elements are synchronized—through correct PUID/PGID assignment, accurate API key entry, and a well-planned volume structure—Bazarr becomes an invisible but powerful asset in the media server stack, ensuring that every movie and episode is perfectly subtitled according to the user's specific linguistic preferences.