Migration from Upstream

Bazarr+ is a drop-in replacement for upstream Bazarr. It uses a compatible database with additional columns added on first run, the same config files, and the same volume paths. Switching takes about five minutes.

The v2.4 additions are additive and non-destructive. Your existing settings, language profiles, providers, and the shared OpenSubtitles-compatible token all carry over. Schema migrations run automatically on first boot, and the old shared compat token is auto-seeded as an "Unlimited Default" key in the new Distribution Hub, so existing integrations keep authorizing without changes.

Back up your config

Before making any changes, copy your entire config directory. This is the directory you mounted as /config in your existing Bazarr container.

Shell 
cp -r ./config ./config-backup-$(date +%Y%m%d)

This gives you a timestamped backup you can restore from if anything goes wrong. The config directory contains your SQLite database (db/bazarr.db), settings, logs, and cached data.

Do not skip this step. While the migration is straightforward and non-destructive, having a backup means you can always go back.

Container swap process

The actual swap is just changing the Docker image name in your compose file.

  1. Stop the current container.
    Shell 
    docker compose down
  2. Update the image in your docker-compose.yml. Change the image line from the upstream image to the Bazarr+ image:
    Before → After 
    # Before (upstream)
image: lscr.io/linuxserver/bazarr:latest
# or
image: ghcr.io/morpheus65535/bazarr:latest

# After (Bazarr+)
image: ghcr.io/lavx/bazarr:latest
  3. Add the companion services. The only companion service recommended now is FlareSolverr, plus the optional AI translator. OpenSubtitles.org is a native Provider Hub plugin in v2.4: install it from the Marketplace, then point its FlareSolverr URL setting at the flaresolverr service below (http://flaresolverr:8191/v1 on a shared Docker network, or http://localhost:8191/v1 with host networking, in which case also publish FlareSolverr's 8191:8191 port or run it on host networking too so 8191 is reachable on the host). There is no separate scraper container anymore.
    docker-compose.yml additions 
    # Add these services:
  # Recommended for the OpenSubtitles.org and many other plugins. Set this container's
  # /v1 URL (http://flaresolverr:8191/v1) in the plugin's FlareSolverr URL. With host
  # networking use http://localhost:8191/v1 and add a "8191:8191" ports mapping below
  # (or run flaresolverr on host networking too) so 8191 is reachable on the host.
  flaresolverr:
    image: ghcr.io/flaresolverr/flaresolverr:latest
    container_name: flaresolverr
    restart: unless-stopped
    environment:
      - LOG_LEVEL=info
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8191/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s

  # AI translation via OpenRouter (free tiers available)
  # Configure the API key in Settings > AI Translator
  ai-subtitle-translator:
    image: ghcr.io/lavx/ai-subtitle-translator:latest
    container_name: ai-subtitle-translator
    restart: unless-stopped
    ports:
      - 8765:8765
    healthcheck:
      test: ["CMD", "curl", "-sf", "http://localhost:8765/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
  4. Start the new stack.
    Shell 
    docker compose up -d

That is it. Open Bazarr+ in your browser and everything should be where you left it.

What changes

After the swap, you get all the Bazarr+ additions on top of your existing setup:

  • Provider priority. A toggle in Settings > Subtitle Sources enables priority-ordered querying with early stop.
  • Bulk operations. Series and Movies pages gain checkboxes and a batch action toolbar.
  • Subtitle editor. A new "Edit" button appears next to each downloaded subtitle.
  • AI translation. Translate subtitles into any language via OpenRouter models. Configure in Settings > AI Translator.
  • Telemetry removed. All Google Analytics tracking code is gone. No data leaves your server.
  • UI improvements. Navigation changes, keyboard shortcuts, and various polish throughout.

What stays the same

  • Database. Your SQLite database is used as-is. Bazarr+ adds a few columns via Alembic migrations on first run (e.g. score_out_of, tvdbId), but these do not break backwards compatibility.
  • Settings. All your provider accounts, language profiles, Sonarr/Radarr connections, and notification settings carry over.
  • History. Your entire download and upgrade history remains intact.
  • Subtitles. All previously downloaded subtitle files stay on disk, untouched.
  • Scheduled tasks. Your scan intervals and other scheduled tasks continue as configured.
  • OpenSubtitles-compatible token. The shared compat token from earlier versions is auto-seeded as an "Unlimited Default" key in the Distribution Hub, so any Jellyfin, VLSub, or custom client using it keeps working unthrottled.

External Integration has moved

One item changed location in v2.4. The old Settings > External Integration page is gone. Endpoint and token management for the OpenSubtitles-compatible API now lives in the Distribution Hub, and /settings/external redirects there. If you bookmarked or scripted against the old page, point it at the Distribution Hub instead. To recover the current shared token, use the "Reveal token" action on the Unlimited Default key.

Password upgrade notice

Upstream Bazarr stores passwords using MD5, which is insecure. On first login after the migration, Bazarr+ will transparently upgrade your password hash to PBKDF2 with 600,000 iterations. This happens automatically when you enter your existing password. No action needed on your part.

Note: If you later revert to upstream Bazarr, you will need to reset your password because upstream cannot read the PBKDF2 hash. See the section below for details.

Reverting if needed

If you want to switch back to upstream Bazarr for any reason:

  1. Stop Bazarr+. Run docker compose down.
  2. Restore your backup. Replace the current config directory with your backup: rm -rf ./config && cp -r ./config-backup-* ./config
  3. Change the image back to the upstream image in your compose file.
  4. Start it. Run docker compose up -d.

If you did not keep a backup and want to revert, there are a few things to be aware of. The password hash in config/config.yaml under auth.password will be in PBKDF2 format, which upstream cannot read. Clear the password field to reset it. Additionally, the series_scores and movie_scores config sections are deleted by Bazarr+, gemini_key is migrated to a gemini_keys list, and the analytics section is removed.

Next steps