GuessIt¶

GuessIt is a python library that extracts as much information as possible from a video filename.

It has a very powerful matcher that allows to guess properties from a video using its filename only. This matcher works with both movies and tv shows episodes.

For example, GuessIt can do the following:

$ guessit "Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi"
For: Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi
GuessIt found: {
    "title": "Treme",
    "season": 1,
    "episode": 3,
    "episode_title": "Right Place, Wrong Time",
    "source": "HDTV",
    "video_codec": "Xvid",
    "release_group": "NoTV",
    "container": "avi",
    "mimetype": "video/x-msvideo",
    "type": "episode"
}

Install¶

Install GuessIt with pip:

pip install guessit

Or add it to your project with uv:

uv add guessit

You can also run the CLI without installing it, with uvx:

uvx guessit "Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi"

You can also install GuessIt from sources.

Usage¶

GuessIt can be used from the command line:

$ guessit "Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi"

Run guessit --help for the full list of options. Use guessit -p to list the properties GuessIt can detect and guessit -V to list their possible values.

It can also be used as a python module:

>>> from guessit import guessit
>>> guessit('Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi')
MatchesDict({'title': 'Treme', 'season': 1, 'episode': 3, 'episode_title': 'Right Place, Wrong Time', 'source': 'HDTV', 'video_codec': 'Xvid', 'release_group': 'NoTV', 'container': 'avi', 'mimetype': 'video/x-msvideo', 'type': 'episode'})

MatchesDict is a dict that keeps matches ordering.

Command line options can be given as dict or string to the second argument. See the API & options reference for the full API and every option.

Configuration¶

Find more about Guessit configuration at configuration page.

Support¶

This project is hosted on GitHub. Feel free to open an issue if you think you have found a bug or something is missing in guessit.

Some filename shapes are inherently ambiguous to a structural parser; the ones guessit deliberately does not resolve are documented on the known limitations page.

GuessIt relies on Rebulk project for pattern and rules registration.

License¶

GuessIt is licensed under the LGPLv3 license.