plex-letterboxd 0.8

Plex to Letterboxd Exporter

Exports Plex watch history and ratings to a Letterboxd‑compatible CSV file using TMDB IDs for reliable matching.

Install

From PyPI:

pip install plex-letterboxd

Or with uv:

uv pip install plex-letterboxd

From source:

git clone https://github.com/brege/plex-letterboxd.git
cd plex-letterboxd
pip install .

Or with uv:

git clone https://github.com/brege/plex-letterboxd.git
cd plex-letterboxd
uv pip install .

Configure

There are two ways to include your Plex token.

Option 1: Set your Plex token in config.yaml:

plex:
  url: http://your-plex-server:32400
  token: PLEX_TOKEN
  timeout: 60

Option 2: Kometa users may source Kometa's config in this project's config.yaml:

kometa:
  config_path: ./path/to/Kometa/config.yml

Exporter options are in config.yaml.

• export: output, after, before, user, library
• csv: rating, review, max_rows, genres, tags, rewatch, mark_rewatch

See config.example.yaml for available options.

Usage

• List users

plex-letterboxd --list-users

• Export for a specific user

plex-letterboxd --user USERNAME --output plex-export.csv

• Export a date range

plex-letterboxd \
    --user USERNAME \
    --after 2024-01-01 \
    --before 2024-12-31 \
    --output plex-export-2024.csv

Import at https://letterboxd.com/import/

See plex-letterboxd --help for CLI options.

Output CSV Columns

Automated Exports

Set up a systemd timer for automated monthly exports with CSV checkpointing.

Setup Timer

Monthly

bash <(curl -s https://raw.githubusercontent.com/brege/plex-letterboxd/refs/heads/main/systemd/install.sh)

Or weekly

bash <(curl -s https://raw.githubusercontent.com/brege/plex-letterboxd/refs/heads/main/systemd/install.sh) weekly

The timer will run the exporter on your chosen schedule, producing CSV files in ~/.config/plex-letterboxd/data/. Configure the output data directory via config.yaml to change.

I suggest running this on the same machine Plex runs on, since it's typically always online.

License

GPLv3