Your Letterboxd

Your Letterboxd is a self-hosted stats dashboard for Letterboxd. It copies your films, ratings, diary and watchlist from your public Letterboxd profile into a SQLite database on your own machine, adds budget, box office, keyword and certification data from TMDB, and shows the results as charts and lists. It runs in Docker and syncs once a day.

Get it on GitHub

Free and open source (AGPL-3.0). Needs Docker and a free TMDB API token.

The Your Letterboxd Overview: tiles for films watched (554), hours watched, average rating against the Letterboxd average, films this month, average runtime, rewatches, liked films and logged against unlogged films, and a Watching Patterns row with binge days, longest streak and most films in one day.
The Overview at the top of the Dashboard.

Why use it

It adds budget, box office, keyword and certification data from TMDB to your films, and keeps all of your data in a SQLite database on your own machine.

How your data gets in

You don’t upload a Letterboxd export. You give the app your Letterboxd username, and it reads your public profile pages with the letterboxdpy library. It collects every film you have marked as watched, including films with no diary date, along with your ratings and likes, every diary entry, your watchlist, and your profile’s favourites and counts. For each film it also reads the film’s Letterboxd page: title, year, runtime, genres, cast and crew, countries, languages, studios and the Letterboxd average rating. Your profile has to be public.

Each film page links to The Movie Database (TMDB). After the Letterboxd sync, the app looks up every film that has no TMDB data yet and stores its budget, worldwide revenue, TMDB rating, US certification, keywords, collection (for example a franchise such as Mission: Impossible) and the services that stream it in the US.

The sync runs on a schedule, once a day by default, and the Sync Now button on the Profile page starts one straight away. There is no sync when the container first starts, so on a new install you press Sync Now or wait for the schedule. The app waits 4 seconds between requests to Letterboxd and 0.3 seconds between requests to TMDB, so the first sync takes at least 4 seconds for every film on the profile. If Letterboxd starts refusing requests, the sync stops and carries on from where it left off at the next run. Films that are already stored are not fetched again.

Dashboard

The Dashboard opens with tiles for films watched, hours watched, your average rating next to the Letterboxd average for the same films, films this month, average runtime, rewatches, liked films, and how many of your films are logged in the diary. Watching Patterns counts binge days (days with two or more films), your longest run of consecutive days with a film, and the most films you watched in one day.

Below these are a calendar heatmap of the last 365 days, a chart of films by day of the week, the distribution of your ratings in half stars, films per month, and films watched per year.

The Watch Activity section: a calendar heatmap of films watched over the last year, and a bar chart of films watched on each day of the week, with Saturday and Sunday far higher than weekdays.
The calendar heatmap and films by day of the week.

The rest of the Dashboard lists your most-watched genres, directors and actors, a breakdown by decade, the longest and shortest film you have seen, your top countries, languages and studios, and your top writers, composers and cinematographers. It ends with posters of your 12 most recently watched films and your recently liked films.

Lists of top genres, top directors and top actors with film counts and bars, a donut chart of films by decade, and Runtime Extremes showing Shōgun at 595 minutes as the longest film and a 7-minute short as the shortest.
Top genres, directors and actors, films by decade, and the longest and shortest films.

Films, Diary and Watchlist

Films shows the poster of every film you have marked as watched, with the year and your rating. You can sort by title, year or rating, and the Unlogged only box shows just the films with no diary entry. Those films carry a “no date” tag, and films you have watched more than once show the number of watches.

Diary lists your diary entries by month, newest first, with the date, poster and your rating. Watchlist shows the films on your Letterboxd watchlist and their total running time in hours.

Each film has its own page with your rating and the Letterboxd average, the synopsis, the cast, countries, languages and studios, the dates you watched it and whether each watch was a rewatch, and the TMDB budget, box office, certification, collection and keywords.

The Films page: 554 watched, 187 logged, 367 unlogged, with an Unlogged only checkbox and sort menus above a grid of film posters, many tagged no date.
The Films page, sorted by title.

Insights

Insights compares your ratings with the Letterboxd averages and uses the TMDB data. Your Rating Personality is your average rating minus the Letterboxd average for the same films. A gap below −0.3 is labelled The Tough Critic, a gap above +0.3 The Generous Viewer, and anything between The Balanced Judge.

Box Office Power adds up the production budgets and worldwide box office of the films you have watched, splits them into indie (under $10 million), mid-budget ($10–50 million) and blockbuster (over $50 million), and lists the biggest budgets and the films that made the most money relative to their budget.

The Insights page: Your Rating Personality shows The Tough Critic, with an average of 2.79 against a Letterboxd average of 3.5 over 271 rated films, and Box Office Power shows the total budget watched, total box office and a budget distribution chart.
Your Rating Personality and Box Office Power.

The page also shows your average rating by genre (genres with at least 5 films), the directors you rate highest (2 or more films) and the actors you rate highest (3 or more films), a breakdown of certifications, the TMDB keywords you rate highest and lowest, your average rating by the year you first watched each film and by the decade it was released, and the franchises you have watched films from.

Your Hidden Gems lists the films you rated above their Letterboxd average, largest gap first, and Your Unpopular Opinions lists the films you rated below it. Each poster shows your rating, the Letterboxd average and the difference.

Your Hidden Gems: five posters of films rated above their Letterboxd average, each with a green badge showing the gap, and Your Unpopular Opinions below with orange badges.
Hidden gems and unpopular opinions.

Data Explorer

Explorer is a table of every watched film, 20 to a page, with your rating, the Letterboxd average, the TMDB rating, the certification and the budget side by side. You can search by title and sort by title, year, your rating, budget, revenue or TMDB rating. Opening a row shows the Letterboxd and TMDB data next to each other, your watches, and the streaming services that carry the film in the US.

The Data Explorer: a search box and sort menus above rows of films, each with a poster, your rating, the Letterboxd and TMDB ratings, a certification badge and the budget.
The Data Explorer, sorted by title.

Installing it

You need Docker with Docker Compose, a public Letterboxd profile, and a TMDB API Read Access Token, which is free from your TMDB account settings. The image is published on Docker Hub as yuyangchee98/your_letterboxd:main and on the GitHub Container Registry. To run it:

  1. Create a docker-compose.yml from the one in the README. It maps port 60007 to the app and keeps the database in a ./data folder.
  2. Create a .env file next to it with LETTERBOXD_USERNAME and TMDB_ACCESS_TOKEN.
  3. Run docker compose up -d and open http://localhost:60007.

SYNC_SCHEDULE sets the sync time as a cron expression (the default is 06:00 every day), and SYNC_MIN_DELAY and TMDB_MIN_DELAY change the wait between requests. The app has a light and a dark theme.

All self-hosted →