Tracking Watched Movies with movie-tracker

5 minute read

Recently, I’ve gotten into the habit of tracking and logging things I’ve done. On my phone, I use to pin-point the places I’ve visited or lived. On this website, I’ve started to track the books I’ve read and the movies I’ve watched. The former is unfortunately a short list, whereas the latter is a very long one. In fact, I’ve already spent way too much time trying to retroactively add movies I’ve seen throughout my life to this list.

Introducing… movie-tracker (v1.0.0)! movie-tracker is a (free and open sourced) text-based user interface application that helps you search for movies and track the ones you’ve watched. I’ve found it super useful for quickly marking hundreds of movies as watched and I hope you find it useful too.

A (self-hosted) asciinema screencast


To get started with movie-tracker,

  1. clone the git repository
  2. Install the Python requirements. I recommend creating a virtualenv and installing the requirements locally (i.e. virtualenv -p python3.6 venv && pip install -r requirements.txt && source venv/bin/activate)
  3. movie-tracker is a curses user interface for The Movie Database API v3, so to use it, you must create an account and register for an API key. The current movie-tracker implementation assumes your API key is set as the TMDB_API_KEY environment variable. You must also pass your TMDB username and password as command line arguments as movie-tracker persists your watched movies as a public TMDB list called “Movies Watched (generated by movie-tracker)”.
$ python -h
usage: [-h] username password

Track movies you have you watched using The Movie Database API v3

positional arguments:
  username    Your The Movie Database username
  password    Your The Movie Database password

optional arguments:
  -h, --help  show this help message and exit


Once you run movie-tracker, you should see a list of the most popular movies on TMDB. You can scroll through the movies using the ↑ and ↓ keys (Page Up and Page Down keys also work as expected). If you hit the Enter key, you’ll mark the selected movie as “watched”, if it’s not already watched (“watched” movies are rendered as green text). If the movie is already marked as “watched”, hitting the Enter key will unmark it. If you scroll over the MORE MOVIES row that is rendered after the movies, movie-tracker will attempt to load more movies from TMDB.

movie-tracker also provides users with a command bar to let them view top movies (:t or :top), movies that are currently playing in theatres (:n or :now_playing), popular movies (:p or :popular) or to let you search for other movies (:s harry potter or :search harry potter). To bring the command bar up, hit the : key. You can also use the command bar to quit the program at any time (:q or :quit) or to save your watched movies to as a YAML file (:w filename.yaml).

Known Bugs and Feature Requests

movie-tracker has sufficiently done its job for my use case, but I have noticed some bugs that haven’t yet been fixed. (I built out the majortiy of its functionality during Yelp’s 25th hackathon which might explain why some of these bugs haven’t been squashed yet). If anyone wants to submit a pull request or officially document these issues, that would be awsome. Here are the bugs:

I’ve also thought of some feature requests that I’ll try to get round to at some point. Here they are:

background Layer 1