Letterboxd CSV IMDb TMDB Mapper

A Node.js script that adds IMDb and TMDb IDs to a Letterboxd-exported CSV file.

Sample CSV generated by this tool:

Original CSV exported from Letterboxd				Data added by this tool
Position	Title	Year	URL	Title Type	TmdbId	Const
1	Apocalypse Now	1979	https://boxd.it/6ZS	Movie	28	tt0078788
2	Spider-Man: Across the Spider-Verse	2023	https://boxd.it/kSz4	Movie	569094	tt9362722
3	Normal People	2020	https://boxd.it/q2VY	TV Series	89905	tt9059760
4	Once Upon a Time in the West	1968	https://boxd.it/2az4	Movie	335	tt0064116
5	Perfect Blue	1997	https://boxd.it/1W7A	Movie	10494	tt0156887

Installation

1. Make sure you have Node.js installed. You can also use Bun.js.

2. Clone or download this repository.

3. Open a terminal inside the letterboxd-csv-imdb-tmdb-mapper folder and run:

   npm install

Usage

1. Export Your Letterboxd Data

Download your Letterboxd data as a ZIP file from here. Extract it and place the .csv files you want to process inside the input folder.

Note: Only put .csv files inside the input folder.
For example, if you want to process likes/films.csv, just copy films.csv into the input folder — do not place the entire likes folder.
The same applies for files under the lists/ folder.

Your input/ folder should look similar to this:

input/
├── your-list-name.csv
├── your-list-name-2.csv
├── diary.csv
├── watched.csv
├── watchlist.csv
├── films.csv
├── ratings.csv
└── ...

2. Run the Script to Add IMDb and TMDb IDs

Process your-list-name.csv or films.csv

npm run scrape "your-list-name.csv"

or

npm run scrape "films.csv"

so on...

✅ Done!

Process diary.csv

Since diary.csv doesn't contain direct film links, process watched.csv first:

npm run scrape "watched.csv"

Then process your diary:

npm run scrape "diary.csv" -- diary

✅ Done!

After processing, a new CSV file with IMDb and TMDb IDs will be created in the output folder.

Additional Arguments

npm run scrape "ratings.csv" -- imdb b10

• imdb: Outputs the CSV in IMDb format.
  (Useful when importing into IMDb using tools like IMDb List Importer, IMDb Ratings Importer, or any tools/website that supports IMDb format.)

• b10: Converts ratings from a 5-point scale to a 10-point scale.

Supported CSV Format

This script supports CSV files exported from the Letterboxd export page.

We follow Letterboxd’s naming scheme, so if you have a CSV from third-party tools like Lizard Letterboxd List Downloader, make sure it follows this format:

Name,Year,Letterboxd URI
Kill Bill: Vol. 1,2003,https://boxd.it/70w

The script requires only three fields:

• Name
• Year
• Letterboxd URI (direct link to the film page)

Known Issues

• reviews.csv is currently not supported due to limitations in the CSV parser.