Importing your data

Letterboxd members can import data in one of three ways: directly to their account (as watched films and/or diary entries, with optional ratings), to a new or existing list, or to their watchlist.

When importing data we support the following formats:

  • Letterboxd import format (CSV)
  • IMDb export files (CSV)
  • Delicious Library v2 or 3 export files (XML)*
  • ICheckMovies export files (custom)

*Delicious Library files are only supported when importing to a list.

Proceed to the Import page (to import watched films), to the editing page for a list, or to your watchlist. For help importing IMDb files, see our migration guide.

Letterboxd import format

“It’s CSVeasy!” —John Siracusa, ATP 351

The Letterboxd import format is a CSV file (with UTF-8 character encoding) that supports the following column titles, in any order (other column titles are ignored). You must include at least one of the first four column titles listed below on the first line of your file, along with any others your file includes data for.

LetterboxdURI String (optional), the boxd.it URI of the matching film or diary entry, example: https://boxd.it/29qU

Note: letterboxd.com URIs are also supported for backwards compatibility.
tmdbID Number (optional), example: 860
imdbID String (optional), example: tt0086567
Title String (optional), used for matching when no ID or URI is provided
Year YYYY (optional), used for matching when no ID or URI is provided
Directors String (optional), used for matching when no ID or URI is provided; multiple entries should be comma-separated
Rating Number (optional, decimals from 0.5–5 including 0.5 increments), rating out of 5
Rating10 Number (optional, integers from 1–10), rating out of 10 (will be converted to 0.5–5 scale)
WatchedDate YYYY-MM-DD (optional), creates a Diary Entry for the film on this day
Rewatch Boolean (optional), if true, sets the rewatch flag on the Diary Entry when WatchedDate is provided
Tags String (optional), added to Diary Entry when WatchedDate is provided; multiple entries should be comma-separated
Review Text/HTML (optional), allows the same HTML tags as the website, added to Diary Entry when WatchedDate is provided, otherwise added as a review with no specified date*

This column header can also be used when importing to a list, to populate the Notes field.

For example, a valid file might look like this:

Title,Year,Rating
Top Gun,1986,5
Gremlins,1984,4.5
"Paris, Texas",1984,4

Your CSV file must use the comma character (,) to delimit columns—do not include a space character immediately after the comma, as this can interfere with the parsing of quoted strings. Strings containing commas (such as film titles, director/tag lists or review text) must be placed inside quotes, eg: "Joel Coen, Ethan Coen". Don’t forget to escape quotes within quoted text, by prefixing them with a backslash (\) character.

Notes on importing

  • There is no undo after the confirmation step. Be careful!
  • The importer shows you a summary of your file before performing the import, so you can fix any mis-matched titles and/or remove any inappropriate entries (such as TV entries that have matched to similarly named films).
  • All films imported to your Films/Diary will be automatically marked as watched (there is an option for marking films watched when importing to a list).
  • The importer updates existing Diary Entries if a film is imported with a WatchedDate that matches an existing entry for the same film already in your Diary, to allow the addition of tags or a review to existing entries.
  • Multiple lines containing the same film with the same WatchedDate will be combined into a single entry when the imported data is saved. If these are legitimately separate entries, you’ll need to add them manually.
  • If both Rating columns contain data on any given line of the file, whichever column appears second in the file will take precedence.
  • The importer works best in Chrome, due to its superior JavaScript engine. If you’re having trouble importing large files, try breaking them into multiple parts (ensure that the first “column header” row of the file exists in each part).
  • There is a file size limit of 1MB, so you’ll need to divide large files into multiple smaller files (the header row containing column names must be in every file).

 

Additional tools

The helper scripts and web apps listed below are created and maintained by third parties. We hope you find them useful, but please contact the individual authors for support.

If you create a helper script that generates files for our importer, let us know.