GuessIt

3.8.0 verified Fri May 01 auth: no python

GuessIt is a Python library and command-line tool that extracts metadata (title, season, episode, year, quality, etc.) from video filenames using a flexible set of rules and regexes. Version 3.8.0 is current. It sees regular maintenance but no fixed release cadence.

pip install guessit

Common errors

error ImportError: cannot import name 'guessit' ↓

cause Installed old version or different package; correct import is from guessit import guessit.

fix

Run 'pip install guessit' and import with 'from guessit import guessit'.

error KeyError: 'title' ↓

cause In some cases, guessit may not find a title (e.g., noise-only filenames). The returned dict might lack expected keys.

fix

Always use .get('title', 'unknown') or check key existence.

error TypeError: guessit() got multiple values for keyword argument 'output' ↓

cause Passing deprecated 'output' parameter in newer versions.

fix

Use options={'output_format': 'json'} instead of output='json'.

Warnings

gotcha guessit returns a dictionary-like object (Guess) that is case-insensitive for keys. Accessing 'title' and 'TITLE' both work. ↓

fix Rely on lower-case keys for consistency, but be aware of case-insensitivity.

gotcha The command-line usage changed: from guessit v3, the CLI is invoked as 'guessit' (no hyphen). The old 'guessit' script (with hyphen) from v2 is removed. ↓

fix Use 'guessit' (not 'guess-it') on the command line.

deprecated The 'guessit' library deprecated the 'output' parameter in the API; use 'options' instead. ↓

fix Replace result = guessit(filename, output='json') with result = guessit(filename, options={'output_format': 'json'}).

Imports

guessit
```
import guessit
```
The main API is a single function import.
guessit.guessit
wrong
```
import guessit; guessit.guessit()
```
correct
```
from guessit import guessit
```
Direct import of the function is cleaner.

Quickstart

Extract metadata from a single filename.

from guessit import guessit

result = guessit('The.Shawshank.Redemption.1994.1080p.BluRay.x264.mkv')
print(result)
# {"title": "The Shawshank Redemption", "year": 1994, "screen_size": "1080p", "source": "BluRay", "video_codec": "x264", "container": "mkv"}