Plexboxd keeps your Letterboxd diary in sync with what you watch on Plex.
Finish a movie and it's logged on the right date, with your rating, your review, and the rewatch flag if you've seen it before.

Quick start · How it works · Configuration · FAQ

---

Important

Plexboxd uses the official Letterboxd API, and nothing else. It doesn't scrape letterboxd.com, drive a browser, reuse browser cookies, or get around any of Letterboxd's protections. There's no browser inside the container at all. Every request to Letterboxd goes through their API with your permission via Letterboxd's own sign-in.

Warning

You need your own Letterboxd API access to use Plexboxd. Letterboxd's API isn't open to everyone: access is granted case by case. Plexboxd does not come with shared credentials, so each person who runs it has to request their own from Letterboxd. Approval is entirely up to Letterboxd and can take a while. See Getting your own Letterboxd API access.

Features

🎬 Automatic diary entries	Every movie you finish on Plex is logged with the date you watched it.
⭐ Ratings come with it	Your Plex star rating carries over exactly. Both use half stars, so 4.5★ stays 4.5★.
✍️ Reviews too	Write a review on Plex and the same text, with the spoiler flag, becomes your Letterboxd review.
🔁 Rewatch detection	Seen it before? It's marked as a rewatch, based on your Plex history and your diary.
⏳ Time to think	Waits a while after the credits (60 minutes by default) so you can rate and review on Plex first.
📝 Late reviews welcome	Review it the next day? The entry is updated for up to a week afterwards.
🧹 No duplicates	Already logged it by hand? It's skipped.
🌊 No flood on day one	Only watches from the day you install are synced. Backfilling is opt-in.
👀 Preview mode	Check each entry and press Post until you trust it, then switch to fully automatic.
🖥️ Web dashboard	Sign-ins, recent activity, settings and diagnostics in one page.
🏠 Runs at home	One Docker container on your NAS or server. Your data stays on your hardware.

How it works

flowchart LR
    A["🎬 You finish a movie<br/>on Plex"] --> B["Plexboxd sees it in your<br/>Plex server's watch history"]
    B --> C{"Wait for your<br/>rating & review"}
    C --> D["Match the film on Letterboxd<br/>by TMDB / IMDb ID"]
    D --> E{"Already in<br/>your diary?"}
    E -- yes --> F["Skip"]
    E -- no --> G["📔 Log diary entry<br/>via the Letterboxd API"]
    G -. "review added later" .-> H["Update the entry"]

Loading

1. Watch. Plexboxd checks your Plex server's watch history every few minutes and picks up movies played on your account. TV episodes are ignored, since Letterboxd is for films.
2. Wait. It gives you a grace period after the movie ends (60 minutes by default), so you can rate or review it on Plex first.
3. Gather. It reads your star rating from your Plex server and your written review from Plex's reviews service.
4. Match. It finds the film on Letterboxd by its TMDB ID (falling back to IMDb), so titles never need to match exactly.
5. Log. If the film isn't already in your diary for that day, it creates a diary entry through the official Letterboxd API. If you review the film later, it updates that entry.

Quick start

You'll need:

• A Plex Media Server you own. No Plex Pass is required.
• Docker and Docker Compose: a NAS (Synology, UGREEN, Unraid, TrueNAS…), a home server, or any always-on machine.
• Your own Letterboxd API client ID and secret, requested from Letterboxd (how). Plexboxd won't work without them.

1. Get the code

git clone https://github.com/RamenNuudlss/PlexBoxd.git
cd PlexBoxd

2. Create your .env file

cp .env.example .env

Open .env and fill it in:

LETTERBOXD_CLIENT_ID=your-client-id         # your own, from Letterboxd
LETTERBOXD_CLIENT_SECRET=your-client-secret
PUBLIC_URL=http://192.168.1.50:8977         # the address you'll open the dashboard at
TZ=America/New_York                         # so diary dates match the day you watched
UI_PASSWORD=                                # optional: password-protect the dashboard

PUBLIC_URL matters: after you sign in, Letterboxd sends you back to PUBLIC_URL/letterboxd/callback, so that exact address has to be the redirect URL registered with your Letterboxd API access.

3. Start it

docker compose up -d --build

It's a small Python image with no browser inside, so it builds in under a minute.

4. Open the dashboard at your PUBLIC_URL and:

1. Click Sign in with Plex. You approve access on plex.tv, and Plexboxd never sees your Plex password.
2. Choose your Plex server.
3. Click Sign in with Letterboxd. You approve access on Letterboxd's own page, and Plexboxd never sees your Letterboxd password.
4. Watch a movie. 🍿

Updating later

git pull
docker compose up -d --build

Your settings and sign-ins live in ./data and are kept across updates.

Tip

Preview mode is on by default, so new entries wait on the dashboard until you press Post. Once the matches look right, turn it off in Settings and everything logs automatically.

The dashboard

Everything happens at http://<your-server-ip>:8977:

• Status at a glance. Whether Plex, Letterboxd and Plex reviews are connected, and whether entries post automatically or wait in preview mode.
• Recent watches. Every movie with its watch date, rating, review, rewatch and spoiler tags, and its status (Waiting, Ready, Logged, Skipped or Failed). Each row has Post, Skip and Retry buttons and a link to the film on Letterboxd.
• Check now. Look at Plex right away instead of waiting for the next check.
• Settings. Everything in the table below.
• Diagnostics. Live checks against Plex and Letterboxd with your sign-ins, for when something isn't syncing.

Configuration

Settings (in the dashboard)

Setting	Default	What it does
Preview mode	On	Hold entries until you press Post
Sync star ratings	On	Carry your Plex rating over
Sync written reviews	On	Carry your Plex review and spoiler flag over
Mark rewatches	On	Flag repeat viewings as rewatches
Wait after a watch	60 min	Time to rate and review on Plex before logging
Check Plex every	300 s	How often to read your watch history
Pick up late reviews for	7 days	How long to keep updating an entry with a later review
Plex account ID	1	Whose watches to follow (1 is the server owner)
Only sync watches from	Install date	Move it earlier to backfill older watches

Environment variables

Variable	Required	Description
LETTERBOXD_CLIENT_ID	✅	Your own Letterboxd API client ID (request it)
LETTERBOXD_CLIENT_SECRET	✅	Your own Letterboxd API client secret
PUBLIC_URL	✅	The address you open the dashboard at, e.g. http://192.168.1.50:8977. Letterboxd's sign-in returns to PUBLIC_URL/letterboxd/callback.
TZ	Recommended	Your time zone, e.g. America/New_York, so diary dates match the day you watched
UI_PASSWORD		Password for the dashboard (any username works)
PORT		Dashboard port (default 8977)
LOG_LEVEL		info (default) or debug

Getting your own Letterboxd API access

Letterboxd's API isn't universal or self-serve. Access is granted case by case, and every Plexboxd user needs their own. There are no shared keys in this project, and there never will be: credentials are issued to the person Letterboxd approved.

How to ask:

1. Email api@letterboxd.com.
2. Briefly explain what you'll use it for. You can copy the template below and change the details.
3. Wait for Letterboxd to reply. Approval is at their discretion, and there's no set timeline.
4. When you get a client ID and secret, put them in your .env file as shown in Quick start.

When Letterboxd asks for a redirect URL, give the address of your Plexboxd dashboard followed by /letterboxd/callback, for example http://192.168.1.50:8977/letterboxd/callback. It must match PUBLIC_URL in your .env.

Email template

Subject: API access request: personal Plex → Letterboxd diary sync (Plexboxd)

Hi Letterboxd team,

I'd like to request API access to run Plexboxd (https://github.com/RamenNuudlss/PlexBoxd),
an open-source, self-hosted tool, for my own account.

It logs films I finish on my Plex server to my Letterboxd diary with the watch date,
and carries over my Plex rating and review (with the spoiler flag) and the rewatch flag.

It acts only on my account, after I sign in with Letterboxd. It needs film lookup by
TMDB/IMDb ID, creating and editing my own log entries, and reading my own diary to avoid
duplicates. That's a handful of requests per film watched, with no scraping or bulk data use.

Thanks,
<your name>
Letterboxd: letterboxd.com/<your-username>

Plexboxd only uses what it needs:

• look up films by TMDB or IMDb ID;
• create and edit your own log entries;
• read your own diary, to avoid duplicates.

Keep your client secret private. It belongs in your .env file, which is already in .gitignore, and should never be committed to a repository, including your fork of this one.

FAQ

Why "official API only"? Wouldn't scraping be easier?

Easier, maybe, but it goes against what Letterboxd allows, it breaks whenever their site changes, and it means handing a tool your login cookies. The official API is stable, respects your account, and is what Letterboxd wants third-party tools to use. Plexboxd will never include a scraping or browser-automation mode.

Why do I have to request my own Letterboxd API access? Can't Plexboxd include a key?

Letterboxd approves API access per applicant, and a client secret is meant to stay private. A key published in an open-source project would be exposed to everyone and would likely be revoked. Each user requests access for themselves, and Letterboxd decides. It's an extra step, but it keeps Plexboxd fully above board with Letterboxd.

Do I need Plex Pass?

No. Plexboxd reads your server's own watch history, so it doesn't rely on Plex Pass webhooks.

What about TV shows?

Letterboxd is films only, so episodes are ignored. Movies in any library are synced.

Will it fill my diary with everything I've ever watched on Plex?

No. On first start it only syncs watches from that moment on. To backfill, set Only sync watches from to an earlier date. Preview mode is a good idea while you do.

How are rewatches detected?

A watch is a rewatch if any of these are true: Plex has an earlier play of the same movie on your account, your Letterboxd diary already has an earlier entry for it, or Plexboxd has logged it before.

I logged a movie by hand on Letterboxd. Will it be logged twice?

No. If your diary already has that film within a day of the Plex watch, Plexboxd skips it.

Where are Plex reviews read from?

Plex stores user reviews on its own servers, not on your Plex server. Plexboxd reads your own reviews through Plex's community API, which Plex hasn't publicly documented. That's the one unofficial interface Plexboxd uses, and it's on the Plex side, read-only, for your own data. If Plex changes it, reviews pause while watches and ratings keep syncing, and the dashboard tells you.

Where is my data stored?

In the ./data folder next to your compose file: settings, sync history, and the access tokens from your Plex and Letterboxd sign-ins. Nothing is sent anywhere except Plex and Letterboxd.

Troubleshooting

What you see	What to do
"Sign in to Letterboxd again"	Your Letterboxd access was revoked or expired. Click Reconnect. Pending watches are held, not lost.
"Plex reviews couldn't be read"	Plex changed its reviews service. Watches and ratings keep syncing. Run Diagnostics and check the issues for a fix.
A movie shows "Skipped: no match"	It has no TMDB/IMDb ID in Plex. Use Fix Match in Plex, then press Retry.
Nothing shows up after watching	Check the Plex account ID setting (1 is the server owner), then run Diagnostics.
Diary dates are a day off	Set TZ in your .env to your time zone, then docker compose up -d.
Letterboxd sign-in says the redirect URL doesn't match	PUBLIC_URL in .env must be exactly the address registered with Letterboxd (redirect PUBLIC_URL/letterboxd/callback).
"Add your LETTERBOXD_CLIENT_ID…"	Your .env is missing your Letterboxd API credentials, or the container wasn't restarted after adding them.

Roadmap

• Plex sign-in, watch history, ratings and reviews
• Rewatch detection, duplicate protection, preview mode, dashboard
• Prebuilt Docker image on GitHub Container Registry
• Multiple Plex users, each with their own Letterboxd account
• Optional push notification when an entry is logged

Contributing

Issues and pull requests are welcome. Run the tests with pip install -r requirements.txt pytest && python -m pytest. Contributions have to keep to the project's one rule: Letterboxd is accessed only through its official API. Pull requests that add scraping, browser automation, or cookie-based access won't be merged.

Disclaimer

Plexboxd is an independent project. It isn't affiliated with, endorsed by, or sponsored by Letterboxd or Plex. "Letterboxd" and "Plex" are trademarks of their respective owners.

License

MIT © RamenNuudls