v2 Breaking Changes

This page summarizes the major, breaking changes introduced in the v2 release.

Important

Upgrading from v1 to v2 is not a seamless process. Please read through all the changes below to understand the necessary migration steps.

It is recommend to backup your existing data and configuration before proceeding. However, migrating your prior data will not be possible due to the significant changes in architecture and schema.

Tip

As you read through the changes, I recommend having a local copy of the example v2 configuration open for reference to see how the new config structure looks in practice.

Project rebrand

The project has been renamed from "PlexAniBridge" to "AniBridge" to reflect its expanded capabilities beyond just Plex integration. As part of this rebrand:

The GitHub repository has moved from https://github.com/eliasbenb/PlexAniBridge to https://github.com/anibridge/anibridge.
The official Docker image has moved from ghcr.io/eliasbenb/plexanibridge:v1 to ghcr.io/anibridge/anibridge:v2.
The official mapping repository has moved from https://github.com/eliasbenb/PlexAniBridge-Mappings to https://github.com/anibridge/anibridge-mappings.
Documentation has been updated to reflect the new project name and URLs.

If you are using Docker, please update your image references accordingly:

# v1 Docker compose
services:
  plexanibridge:
    image: ghcr.io/eliasbenb/plexanibridge:v1
    ...

# v2 Docker compose
services:
  anibridge:
    image: ghcr.io/anibridge/anibridge:v2
    ...

Configuration changes

v2 introduces a provider-agnostic architecture, allowing AniBridge to support multiple media library or list providers beyond Plex and AniList. This change required significant refactoring of the codebase and configuration schema. As a result, many configuration options and mappings have changed to accommodate this new architecture:

YAML configuration

v1 allowed multiple config sources (YAML, JSON, and environment variables). v2 only accepts a single YAML config file.

If you used environment variables or a JSON file to configure your v1 instance, move those values into the YAML file located at $AB_DATA_PATH/config.yaml.

Global config nesting

In v1, values defined at the root level were implicitly global/shared across profiles. In v2, you must explicitly nest these shared options under a global_config key.

Note: certain application-level settings (like log_level, mappings_url, web, etc.) remain at the root level.

Example conversion:

# v1 config
sync_modes: ["periodic", "webhook"]
sync_interval: 3600
profiles:
  some_profile: ...

# v2 config
global_config:
  scan_modes: ["periodic", "webhook"]
  scan_interval: 3600
profiles:
  some_profile: ...

Key renames and nesting

Some previously existing configuration keys were renamed for clarity:

sync_modes → scan_modes
sync_interval → scan_interval

Configuration for the web UI is now nested under a web key:

web_enabled → web.enabled
web_host → web.host
web_port → web.port
web_basic_auth_username → web.basic_auth.username
web_basic_auth_password → web.basic_auth.password
web_basic_auth_htpasswd_path → web.basic_auth.htpasswd_path
web_basic_auth_realm → web.basic_auth.realm

Provider-first schema

v2 is provider-agnostic. Users can select which library and list providers to use through the config.

Each profile must declare its library_provider and list_provider, and provider-specific settings must be nested under a library_provider_config and list_provider_config key respectively.

AniBridge currently supports these built-in providers (with more planned):

Library providers: Plex (plex), Jellyfin (jellyfin), Emby (emby)
List providers: AniList (anilist), MyAnimeList (mal)

For advanced users: you can also load 3rd-party providers that implement the library base or list base by including the full Python class path in provider_classes. This opens up possibilities for custom or community-developed providers.

Example for Plex-AniList:

# v1 config
profiles:
  some_profile:
    plex_url: ...
    plex_token: ...
    plex_user: ...
    # plex_sections: []
    # plex_genres: []
    anilist_token: ...

# v2 config
profiles:
  some_profile:
    library_provider: plex
    list_provider: anilist
    library_provider_config:
      plex:
        url: ...
        token: ...
        # home_user: ... # renamed from "user" and now only works for Plex Home users, see more details below
        # sections: []
        # genres: []
    list_provider_config:
      anilist:
        token: ...

Plex user config changes

The plex_user option from v1 has been renamed to home_user in v2 and its behavior has changed. In v1, this option was used to specify any Plex user to switch to after authenticating with the provided token. In v2, this option is specifically for switching between Plex Home users.

This change was made due to a breaking change in the Plex API (read more here). Authentication in v2 is split into two categories:

Standard authentication: If home_user is not set, the provider will authenticate using the provided token and operate under that user. Unlike v1, you can now authenticate with any Plex user token, not just the Home owner (as long as the user has access to the Plex server).
Home user switching: If home_user is set, the provider will first authenticate with the provided token (which must belong to the Plex Home owner), then attempt to switch to the specified Home user. If the token does not belong to the Home owner or if the specified user is not a valid Home user, authentication will fail.

This change was made out of necessity due to the Plex API change, but it also provides more flexibility. Now, users can authenticate their personal accounts without needing their Plex Home owner's token.

Additionally, prior to v2, non-owner users were unable to access certain Plex API features, including fetching watchlist status and user reviews from the Plex Community API. In v2, all users can access all features equally.

Mapping schema

Significant changes were made to the mapping schema in v2 to increase flexibility under the new provider-agnostic architecture. As a result, all custom mappings from v1 are incompatible with v2. Users must recreate any custom mappings using the new schema defined in the AniBridge Mappings repository. See the repository for more detailed documentation on the new mapping format.

Example conversion:

# v1 custom mapping
1: # Some AniList ID
  tmdb_show_id: 12345
  tmdb_mappings:
    s1: "e1-e12"
  tvdb_show_id: 67890
  tvdb_mappings:
    s1: "e1-e12"

# v2 custom mapping
anilist:1: # Specify the source descriptor (<provider>:<id><:optional scope>)
  tmdb_show:12345:s1:
    "1-12": "1-12" # AniList 1-12 maps to TMDB 1-12
  tvdb_show:67890:s1:
    "1-12": "1-12" # AniList 1-12 maps to TVDB 1-12

Note

The old format cannot be converted automatically due to the v2 schema requiring new data (both a source and target episode range).

Sync rules

In v1, users could set excluded_sync_fields to prevent certain fields from being synced. In v2, this behavior is handled by sync_rules, which also provides additional granular control over how syncing operates on a per-field basis that you can read about here.

# v1 config
global_config:
  excluded_sync_fields: ["status", "score"]

# v2 config
global_config:
  sync_rules:
    status: false
    user_rating: false

Destructive sync changes

In v1, the destructive_sync option controlled both:

Deleting list entries (destructive deletions), and
Allowing regressive field updates (e.g., decreasing progress or changing status from "completed" back to "current").

In v2, this behavior has been split for greater precision:

destructive_sync now only controls whether list entries can be deleted.
Regressive field updates are now managed exclusively through sync_rules. There is a pre-defined prevent_regressions template that you can apply to mimic the old behavior sync_rules: { templates: [prevent_regressions] }. Alternatively, you can create custom rules to allow regressions on certain fields while preventing them on others, which was not possible in v1. Read more about this in the sync rules documentation.

Database

The local database schema had to be overhauled to support the new provider-agnostic architecture. As a result, it was decided to reset the database for v2. Migration from v1 to v2 is not supported, users must start with a fresh database.

Important

The v2 release resets the database migration history and uses a new SQLite filename (plexanibridge.db → anibridge.db).

As a result, all existing sync history and pins will be lost when upgrading from v1 to v2.

Platform and runtime

For users running AniBridge in Docker, please switch to the new v2 image: ghcr.io/anibridge/anibridge:v2.

For users running from source, ensure your Python environment is upgraded to at least Python 3.14, as v2 requires this version or higher.