Cinemagoer: a local SQLite front end for the IMDb public datasets, after the WAF

The scope change of April 2026 and the split into two packages

Cinemagoer was previously known as IMDbPY, and the most important thing to know about the current version is that it does less than the old one. The project carries a revamp notice stating that starting on April 2026 the scope of the project shifted significantly due to the introduction of a WAF in front of the IMDb website. From that day the project can no longer guarantee that the package will work as expected with IMDb data, from a technical and a legal standpoint, and the scope of Cinemagoer was limited to the handling of the dataset that is freely distributed by IMDb.

That is the whole architecture change. Instead of a scraper that fetched pages and parsed them on demand, the package is now a front end to a local database that you populate yourself from the published dataset files.

The scraping capability was not deleted, it was moved. The README points to cinemagoerng for anyone who still needs IMDb web-page parsing, and describes it as focused on parsing IMDb web pages while requiring you to provide the function used to fetch those pages. That is a meaningful difference: the fetching is now your responsibility, not the library's. The upstream project, Cinemagoer, stays on the dataset side.

The other constant across the rename is the disclaimer. The project description states that the authors are not affiliated in any way to Internet Movie Database Inc., and the README points to DISCLAIMER.txt for details about data licenses, in two separate places. The copyright notice runs from 2004 to 2026 for Davide Alberani and others, and the licence is GPL version 2 or later.

The primary language listed for the repository is HTML, which reflects the ancestry of the project as a parser rather than its current shape. The Python package lives in the imdb/ directory, with a bin/ directory for the command line tools.

Installing the package, and the optional database backend

The install section prefers the repository over the index:

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

and offers PyPI as the alternative:

pip install cinemagoer

The base installation includes native SQLite support. That is the important default, because SQLite is what the import workflow in the README uses and what the example opens. For PostgreSQL, MariaDB, MySQL, or an explicitly selected SQLAlchemy dialect, you install the optional integration and your chosen database driver:

pip install "cinemagoer[sqlalchemy]"

The extra is named sqlalchemy and the pyproject.toml pins it as sqlalchemy>=2.0.51,<2.1, an unusually narrow range that tells you the code is tested against a specific SQLAlchemy generation and has not been validated against the next one.

The package itself declares no required dependencies. The dependencies list in pyproject.toml is empty, and requires-python is >=3.10. The classifiers list Python 3.10 through 3.14, so the support floor is recent and deliberate.

There is an oddity worth knowing about the version. The pyproject.toml says version = 2026.08.25, while the tagged releases listed for the project are 2026.08.20, 2026.06.27 and 2023.05.01. The package uses a calendar date as its version, which is a good fit for a tool that tracks the shape of a changing dataset, and it explains the odd jump from 2023.05.01 to 2026.06.27 in the release list. The gap is not a typo, it is two and a half years with no release tag, and the current date-based numbering started after that.

The package description in the metadata is short: Retrieve data from IMDb.

The import step is the real work, and it happens before your code runs

Nothing works until you have a populated database, and the README is explicit about the order of operations in a note attached to the example. Cinemagoer reads data from a local database populated from IMDb datasets. Before running Python examples you download the *.tsv.gz files from the IMDb datasets site, or run download-from-s3, then import them with s32cinemagoer.py, then open the populated database with Cinemagoer.

The import command takes a path to the downloaded files and a database URL:

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

SQLite works with a base installation. Any SQLAlchemy-supported database can be used after installing the sqlalchemy extra and its DBAPI driver, which means the same import script writes to Postgres or MySQL if that is what you already run.

The s32 prefix in s32cinemagoer.py is a legacy of the original IMDbPY naming and refers to the SQL variant of the tool, as opposed to the older web-parsing mode. The tool lives in the bin/ directory, and the repository also has tools/ and a build_support.py, msgfmt.py, rebuildmo.py and generatepot.py, the last of which suggests the project ships translated message catalogues.

The shape of the data is the thing to plan for. The source is a set of TSV files, so your database is a set of denormalised tables keyed by IMDb identifiers, and the Python API is a query layer over it. The example in the README shows the identifier style, with a movie fetched by its numeric id:

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')

The first argument to Cinemagoer is 's3', which selects the dataset-backed mode rather than the web-parsing mode, and the uri keyword points it at the local database. That pairing is the API change that catches people out when they follow an older tutorial.

Two things stand out about the API. First, the result objects behave like dictionaries, since the example iterates movie['directors'] and prints director['name'] from each element, but the person search results are objects with attributes, since the example reads person.personID and person['name'] on the same object. Second, get_movie takes a string id even though it looks numeric.

What the API gives you: movies, people, search

The example covers the three operations a typical consumer needs, and they are worth reading together because they show the data model's grain.

Movie lookup returns a record with nested collections. The example iterates movie['directors'] and prints each director's name, and then iterates movie['genres'] and prints the genre objects directly, which means genres are simple values while directors are records with a name and probably an id.

# 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)

Person search returns a sequence of candidates:

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

That loop mixes the two access styles deliberately, and it tells you that a person record carries a personID attribute alongside a name key. The personID is the value you would feed back into a lookup, and it is the join key that connects the people dataset to the titles and principals data.

The key features the README lists are short: written in Python 3, platform-independent, a simple and complete API, and released under the terms of the GPL 2 license. The claim of a complete API is about surface area rather than capability, and it should be read in the context of the narrowed scope. It is complete for the dataset, which is a bounded and stable thing, rather than for IMDb as a website.

The README also states that Cinemagoer powers many other software and has been used in various research papers, with a link to an ecosystem page for the curious. That is a reasonable signal that the dataset-backed mode has a real user base, since anything built on a live scrape would have had to change with the WAF.

Help is split across three places: a support page on the project homepage, the online documentation on Read The Docs, and the sources on GitHub. The CHANGELOG.txt and CONTRIBUTOR_GUIDE.rst are in the repository, and the contributor guide is linked from a documentation branch of the repository rather than from master, which is a small sign of how documentation work is currently staged.

Tooling, licensing files and what a consumer has to sort out

The pyproject.toml shows a project that has been modernised in its tooling while keeping its public API conservative.

The dependency groups are separated by purpose. The test group uses pytest>=9.1.1 and pytest-cov>=7.1.0, the style group uses ruff>=0.15.22, the doc group uses sphinx>=8.1.3,<9 with sphinx-rtd-theme>=3.1.0, the tox group uses tox-uv>=1.35.2, and the package group uses twine>=6.2.0. A dev group includes all of those plus the sqlalchemy pin. This is a PEP 735 style dependency group layout rather than extras for development tools, which is the current recommendation, and it keeps the installable package free of any test or lint dependency.

The repository has a uv.lock file, so the toolchain is uv for locking. The presence of AGENTS.md, CLAUDE.md and GEMINI.md at the top level says something about how the maintainer expects AI tools to be used in the repository, and is unusual enough to be worth a look if you plan to contribute.

The licence file list is short and deliberate. LICENSE.txt holds the GPL-2.0-or-later terms, CONTRIBUTORS.txt lists the people who share copyright over specific portions of code, and DISCLAIMER.txt holds the recommendations. The README repeats the disclaimer pointer in the introduction and again in the licence section, and the project description itself notes the non-affiliation with Internet Movie Database Inc.

That DISCLAIMER.txt is the file a consumer should read first, because the GPL covers the code, not the data. The data comes from IMDb's freely distributed datasets under their own terms, and the project has no affiliation with the company. A package that is GPL-2.0-or-later in code and importer-neutral about the data is a common arrangement, but the data terms are what constrain a commercial deployment, and this project routes you to a separate document for them rather than restating them.

The maintenance picture is a date rather than a label. The repository is not archived, the last push was on 2026-10-19, and the two most recent releases are 2026.08.20 and 2026.06.27, both after the April 2026 scope change. The package version in pyproject.toml is 2026.08.25, which is ahead of the 2026.08.20 tag, so the branch carries work newer than the last release.

Editorial conclusion

Cinemagoer fits a researcher or application that needs structured movie, person and company data and is willing to work from the IMDb public dataset files rather than live web pages, since the WAF removed the scraping path from the package. It is the wrong tool if you need live page data, in which case the project points to the separate cinemagoerng package, and the wrong tool for a closed-source product given the GPL-2.0-or-later licence. Before adopting, read DISCLAIMER.txt, which the README repeatedly refers you to for the data licence terms, and confirm the import step fits your disk and time budget, because building the database is a separate step from installing the package.

Frequently asked questions

Official sources

1. cinemagoer/cinemagoer on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases