---
id: cinemagoer
version: "2026.6.27"
license: GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and… (full text in the JSON record)
license_treatment: copyleft
maintenance: active
---

# cinemagoer — Retrieve data from IMDb.

License: copyleft · Maintenance: active · Downloads: 76.6K/mo

## What it is and what it does

Cinemagoer is a Python library for querying IMDb movie, actor, director, and company data from locally-hosted databases populated with IMDb's freely distributed TSV datasets. It is not a web scraper—as of April 2026, the project explicitly shifted away from IMDb website parsing due to WAF restrictions and now focuses solely on handling the official downloadable datasets. The library uses SQLAlchemy as its database abstraction layer, supporting any SQLAlchemy-compatible database backend.

You populate a local database by downloading IMDb's TSV files and importing them with s32cinemagoer.py, then query that database through Cinemagoer's API. The library offers a simple interface for retrieving movies by ID, searching for people by name, and accessing related metadata like cast, crew, genres, and character information. It requires Python 3.10 or later and depends on lxml and sqlalchemy.

Use it for:

- Build a film discovery application using local IMDb data without relying on external APIs.
- Conduct film research or analysis by querying actor filmographies, director credits, and genre classifications.
- Create a personal movie database application with cast and crew information for offline use.
- Develop a command-line tool to search and display movie details, actor profiles, and production credits.
- Integrate IMDb metadata into a media management or cataloging system using a local database.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Cinemagoer retrieves and queries movie, actor, director, and company data from IMDb's freely distributed datasets using a local SQLAlchemy-backed database.

Yes, if you need offline IMDb data access and are willing to manage a local database. The package is actively maintained, has low install friction, and offers a clean API for dataset queries. Not suitable if you need real-time web scraping of IMDb pages. GPLv2 copyleft licensing requires derivative works to be open-source.

## Install

pip install cinemagoer
uv add cinemagoer
poetry add cinemagoer

## Installing cinemagoer

Before you install: Low install friction with a pure-Python wheel and only two runtime dependencies (lxml, sqlalchemy). Actively maintained with a recent release (48 days old) and ongoing repository activity.

License in practice: Released under GPLv2, a copyleft license. Any derivative work or distribution must also be licensed under GPLv2 or later and include source code availability.

Quickstart:

pip install cinemagoer

from cinemagoer import Cinemagoer
ia = Cinemagoer('s3', uri='sqlite:///cinemagoer.db')
movie = ia.get_movie('0133093')
for director in movie['directors']:
    print(director['name'])

You must first download IMDb TSV datasets from https://datasets.imdbws.com/, import them using s32cinemagoer.py into a SQLAlchemy-supported database, and provide the database URI to Cinemagoer.

Verify before relying:

- Whether the WAF introduced in April 2026 affects any remaining functionality beyond the documented dataset-only scope.
- Performance characteristics and scalability limits for large IMDb dataset queries.
- Compatibility details with specific SQLAlchemy database backends beyond SQLite.

## Package facts

- License: GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and… (full text in the JSON record) (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 76.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

imdb data retrieval python, movie database query library, film metadata lookup, actor director information api, cinema data management, imdb dataset parser, movie cast crew search, imdb-data, offline-database, film-metadata

[View on SkillFed](https://skillfed.io/packages/cinemagoer) · [View on PyPI](https://pypi.org/project/cinemagoer/)