Cinemagoer

Cinemagoer (previously known as IMDbPY) is a Python package for retrieving and managing IMDb data about movies, people and companies from IMDb non-commercial downloadable datasets.

This project and its authors are not affiliated in any way to Internet Movie Database Inc.; see the DISCLAIMER.txt file for details about data licenses.

Revamp notice

Starting on April 2026, the scope of this project shifted significantly due to the introduction of a WAF in front of the IMDb website. From that day we can no longer guarantee that the package will work as expected with IMDb data (from a technical and legal standpoints), and we limited the scope of Cinemagoer to the handling of the dataset that is freely distributed by IMDb.

If you still need IMDb web-page parsing, see cinemagoerng. It is focused on parsing IMDb web pages, but requires you to provide the function used to fetch those pages.

Main features

written in Python 3
platform-independent
simple and complete API
released under the terms of the GPL 2 license

Cinemagoer powers many other software and has been used in various research papers. Curious about that?

Installation

Whenever possible, please use the latest version from the repository:

pip install git+https://github.com/cinemagoer/cinemagoer

But if you want, you can also install the latest release from PyPI:

pip install cinemagoer

Example

Here’s an example that demonstrates how to use Cinemagoer:

Note

Cinemagoer reads data from a local database populated from IMDb datasets. Before running Python examples:

Download the *.tsv.gz files from https://datasets.imdbws.com/ (or run download-from-s3)
Import them with s32cinemagoer.py
Open the populated database with Cinemagoer

SQLite is used in examples for simplicity, but any SQLAlchemy-supported database can be used.

s32cinemagoer.py /path/to/imdb-tsv-files/ sqlite:///cinemagoer.db

from imdb import Cinemagoer

 # Open the SQLite database populated with s32cinemagoer.py.
 ia = Cinemagoer('s3', uri='sqlite:///cinemagoer.db')

# get a movie
movie = ia.get_movie('0133093')

# print the names of the directors of the movie
print('Directors:')
for director in movie['directors']:
    print(director['name'])

# print the genres of the movie
print('Genres:')
for genre in movie['genres']:
    print(genre)

# search for a person name
people = ia.search_person('Mel Gibson')
for person in people:
   print(person.personID, person['name'])

Getting help

Please refer to the support page on the project homepage and to the the online documentation on Read The Docs.

The sources are available on GitHub.

Contribute

Visit the CONTRIBUTOR_GUIDE.rst to learn how you can contribute to the Cinemagoer package.

License

Cinemagoer is released under the GPL license, version 2 or later. Read the included LICENSE.txt file for details.

NOTE: For a list of persons who share the copyright over specific portions of code, see the CONTRIBUTORS.txt file.

NOTE: See also the recommendations in the DISCLAIMER.txt file.

Disclaimer

Cinemagoer and its authors are not affiliated with Internet Movie Database Inc.

IMDb is a trademark of Internet Movie Database Inc., and all content and data included on the IMDb’s site is the property of IMDb or its content suppliers and protected by United States and international copyright laws.

Please read the IMDb’s conditions of use on their website:

https://www.imdb.com/conditions
https://www.imdb.com/licensing
any other notice on the https://www.imdb.com/ site

Contents: