Configuration

Example

Below is an example .env file for PlexAniBridge:

#== Global Defaults ==#
PAB_ANILIST_TOKEN=...
PAB_PLEX_TOKEN=...
PAB_PLEX_USER=...
PAB_PLEX_URL=...
# PAB_PLEX_SECTIONS=[]
# PAB_PLEX_GENRES=[]
# PAB_PLEX_METADATA_SOURCE="local"
# PAB_SYNC_INTERVAL=86400
# PAB_SYNC_MODES=["periodic", "poll", "webhook"]
# PAB_FULL_SCAN=false
# PAB_DESTRUCTIVE_SYNC=false
# PAB_EXCLUDED_SYNC_FIELDS=["notes", "score"]
# PAB_DRY_RUN=false
# PAB_BACKUP_RETENTION_DAYS=30
# PAB_BATCH_REQUESTS=false
# PAB_SEARCH_FALLBACK_THRESHOLD=-1

#== Profile Overrides ==#
# PAB_PROFILES__example__$FIELD=$VALUE

#== Global Settings ==#
# PAB_DATA_PATH="./data"
# PAB_LOG_LEVEL="INFO"
# PAB_MAPPINGS_URL="https://raw.githubusercontent.com/eliasbenb/PlexAniBridge-Mappings/v2/mappings.json"
# PAB_WEB_ENABLED=true
# PAB_WEB_HOST="0.0.0.0"
# PAB_WEB_PORT=4848
# PAB_WEB_BASIC_AUTH_USERNAME=null
# PAB_WEB_BASIC_AUTH_PASSWORD=null
# PAB_WEB_BASIC_AUTH_HTPASSWD_PATH=null
# PAB_WEB_BASIC_AUTH_REALM="PlexAniBridge"

#== Global Defaults ==#
anilist_token: ...
plex_token: ...
plex_user: ...
plex_url: ...
# plex_sections: []
# plex_genres: []
# plex_metadata_source: "local"
# sync_interval: 86400
# sync_modes: ["periodic", "poll", "webhook"]
# full_scan: false
# destructive_sync: false
# excluded_sync_fields: ["notes", "score"]
# dry_run: false
# backup_retention_days: 30
# batch_requests: false
# search_fallback_threshold: -1

#== Profile Overrides ==#
# profiles:
#     example:
#         $field: $value

#== Global Settings ==#
# data_path: "./data"
# log_level: "INFO"
# mappings_url: "https://raw.githubusercontent.com/eliasbenb/PlexAniBridge-Mappings/v2/mappings.json"
# web_enabled: true
# web_host: "0.0.0.0"
# web_port: 4848
# web_basic_auth_username: null
# web_basic_auth_password: null
# web_basic_auth_htpasswd_path: null
# web_basic_auth_realm: "PlexAniBridge"

Configuration Hierarchy

Settings are applied in the following order:

1. Profile-specific settings (highest priority)
2. Global default settings (medium priority)
3. Built-in defaults (lowest priority)

For example, if PAB_SYNC_INTERVAL=900 is set globally and PAB_PROFILES__personal__SYNC_INTERVAL=1800 is set for a specific profile, the profile named 'personal' will use 1800 seconds as the sync interval while other profiles will use 900 seconds. If PAB_PROFILES__personal__SYNC_INTERVAL is unset it falls back to the application's built-in default of 86400 seconds (24 hours).

Configuration Options

ANILIST_TOKEN

str (Required)

AniList API access token for this profile.

Generate AniList Token

PLEX_TOKEN

str (Required)

Plex API access token (X-Plex-Token) belonging to the admin user of the server.

Finding the Plex Token

PLEX_USER

str (Required)

Plex user to sync for this profile. Can be identified by:

• Plex account username: "username"
• Plex account email: "[email protected]"
• Plex Home user name: "Home User"

PLEX_URL

str (Required)

URL to your Plex server that the PlexAniBridge host can access.

PLEX_SECTIONS

list[str] (Optional, default: [])

An optional list of Plex library sections to filter by. If specified, only items in these sections will be scanned.

["Anime", "Anime Movies"]

PLEX_GENRES

list[str] (Optional, default: [])

An optional list of Plex genres to filter by. If specified, only items with these genres will be scanned.

["Anime", "Animation"]

This is useful for scanning for only Anime content in a mixed library.

PLEX_METADATA_SOURCE

Enum("local", "online") (Optional, default: "local")

Determines the source of Plex metadata to use when syncing:

• local: Use metadata stored locally on the Plex server.
• online: Fetch metadata from Plex's servers using the Plex Metadata provider.

SYNC_INTERVAL

int (Optional, default: 86400)

Interval in seconds to sync when using the periodic sync mode

SYNC_MODES

list[Enum("periodic", "poll", "webhook")] (Optional, default: ["periodic", "poll", "webhook"])

Determines the triggers for scanning:

• periodic: Scan all items at the specified sync interval.
• poll: Poll for changes every 30 seconds, making incremental updates.
• webhook: Trigger syncs via Plex webhook payloads.

Setting SYNC_MODES to None or an empty list will cause the application to perform a single scan on startup and then exit.

By default, all three modes are enabled, allowing for instant, incremental updates via polling and webhooks, as well as a full periodic scan every SYNC_INTERVAL seconds (default: 24 hours) to catch any failed/missed updates.

FULL_SCAN

bool (Optional, default: False)

When enabled, the scan process will include all items, regardless of watch activity. By default, only watched items are scanned.

DESTRUCTIVE_SYNC

bool (Optional, default: False)

Allows regressive updates and deletions, which can cause data loss.

EXCLUDED_SYNC_FIELDS

list[Enum("status", "score", "progress", "repeat", "notes", "started_at", "completed_at")] (Optional, default: ["notes", "score"])

Specifies which fields should not be synced. Available fields:

• status (planning, current, completed, dropped, paused)
• score (rating on a normalized scale)
• progress (episodes watched)
• repeat (rewatch count)
• notes (text reviews)
• started_at (start date)
• completed_at (completion date)

DRY_RUN

bool (Optional, default: False)

When enabled:

• AniList data is not modified.
• Logs show what changes would have been made.

BACKUP_RETENTION_DAYS

int (Optional, default: 30)

Controls how many days PlexAniBridge keeps AniList backup snapshots before pruning older files. Set to 0 to disable automatic cleanup and retain all backups indefinitely.

BATCH_REQUESTS

bool (Optional, default: False)

When enabled, AniList API requests are made in batches:

1. Prior to syncing, a batch of requests is created to retrieve all the entries that will be worked on.
2. Post-sync, a batch of requests is created to update all the entries that were changed.

This can significantly reduce rate limiting, but at the cost of atomicity. If any request in the batch fails, the entire batch will fail.

For example, if a sync job finds 10 items to update with BATCH_REQUESTS enabled, all 10 requests will be sent at once. If any of the requests fail, all 10 updates will fail.

SEARCH_FALLBACK_THRESHOLD

int (Optional, default: -1)

Determines how similar a title must be to the search query as a percentage to be considered a match.

The default behavior is to disable searching completely and only rely on the community and local mappings database.

The higher the value, the more strict the title matching. A value of 100 requires an exact match, while 0 will match the first result returned by AniList, regardless of similarity.

Global Configuration Options

These global settings cannot be overridden on the profile level and apply to all profiles.

PAB_DATA_PATH

str (Optional, default: ./data)

Path to store the database, backups, and custom mappings. This is shared across all profiles.

PAB_LOG_LEVEL

Enum("DEBUG", "INFO", "SUCCESS", "WARNING", "ERROR", "CRITICAL") (Optional, default: INFO)

Sets logging verbosity for the entire application.

PAB_MAPPINGS_URL

str (Optional, default: https://raw.githubusercontent.com/eliasbenb/PlexAniBridge-Mappings/v2/mappings.json)

URL to the upstream mappings source. This can be a JSON or YAML file.

This option is only intended for advanced users who want to use their own upstream mappings source or disable upstream mappings entirely. For most users, it is recommended to keep the default value.

PAB_WEB_ENABLED

bool (Optional, default: True)

When enabled, the web interface is accessible.

PAB_WEB_HOST

str (Optional, default: 0.0.0.0)

The host address for the web interface.

PAB_WEB_PORT

int (Optional, default: 4848)

The port for the web interface.

PAB_WEB_BASIC_AUTH_USERNAME

str (Optional, default: None)

HTTP Basic Authentication username for the web UI. Basic Auth is enabled only when both the username and password are provided. Leave unset to disable authentication.

PAB_WEB_BASIC_AUTH_PASSWORD

str (Optional, default: None)

HTTP Basic Authentication password for the web UI. Basic Auth is enabled only when both the username and password are provided. Leave unset to disable authentication.

PAB_WEB_BASIC_AUTH_HTPASSWD_PATH

str (Optional, default: None)

Path to an Apache htpasswd file containing user credentials for HTTP Basic Authentication. When set, the web UI validates requests against this file. Only bcrypt (recommended) and SHA1 hashed passwords are supported.

Providing an htpasswd file allows you to manage multiple users and rotate passwords without exposing plaintext credentials in the configuration. You may still set PAB_WEB_BASIC_AUTH_USERNAME and PAB_WEB_BASIC_AUTH_PASSWORD; both authentication methods will be accepted.

PAB_WEB_BASIC_AUTH_REALM

str (Optional, default: PlexAniBridge)

Realm label presented in the browser Basic Auth prompt and WWW-Authenticate response header.

Advanced Examples

Multiple Users

This example demonstrates configuring three distinct profiles, each with their own AniList accounts, Plex users, and customized sync preferences.

# Global defaults shared by all profiles
PAB_PLEX_TOKEN=admin_plex_token
PAB_PLEX_URL=http://localhost:32400
PAB_SYNC_MODES=["periodic"]

# Admin user - aggressive sync with full features
PAB_PROFILES__admin__ANILIST_TOKEN=admin_anilist_token
PAB_PROFILES__admin__PLEX_USER=admin_plex_user
PAB_PROFILES__admin__DESTRUCTIVE_SYNC=True
PAB_PROFILES__admin__EXCLUDED_SYNC_FIELDS=[]

# Family member - typical sync
PAB_PROFILES__family__ANILIST_TOKEN=family_anilist_token
PAB_PROFILES__family__PLEX_USER=family_plex_user

# Guest user - minimal sync
PAB_PROFILES__guest__ANILIST_TOKEN=guest_anilist_token
PAB_PROFILES__guest__PLEX_USER=guest_plex_user
PAB_PROFILES__guest__EXCLUDED_SYNC_FIELDS=["notes", "score", "repeat", "started_at", "completed_at"]

Per-Library Profiles

This example shows how to create separate profiles for different Plex libraries, allowing for tailored sync settings based on content type.

# Global defaults shared by all profiles
PAB_ANILIST_TOKEN=global_anilist_token
PAB_PLEX_TOKEN=admin_plex_token
PAB_PLEX_USER=admin_plex_user
PAB_PLEX_URL=http://localhost:32400

# Movies library - aggressive sync with full features
PAB_PROFILES__movies__PLEX_SECTIONS=["Anime Movies"]
PAB_PROFILES__movies__FULL_SCAN=True
PAB_PROFILES__movies__SYNC_INTERVAL=1800
PAB_PROFILES__movies__EXCLUDED_SYNC_FIELDS=[]

# TV Shows library - more conservative with updates
PAB_PROFILES__tvshows__PLEX_SECTIONS=["Anime"]
PAB_PROFILES__tvshows__SYNC_MODES=["periodic"]