Skip to main content

GuessIt - a library for guessing information from video filenames.

Project description


.. image::
:alt: Latest Version

.. image::
:alt: LGPLv3 License

.. image::
:alt: Build Status

.. image::
:alt: Coveralls

`HuBoard <>`_

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",
"format": "HDTV",
"video_codec": "XviD",
"release_group": "NoTV",
"container": "avi",
"mimetype": "video/x-msvideo",
"type": "episode"

More information are available at `ReadTheDocs <>`_.

Migration note
GuessIt 2 has been rewriten from scratch. GuessIt is now a release name parser only, and support for additional
features like hashes computations has been dropped.

To migrate from guessit ``0.x`` or ``1.x``, please read
`migration.rst <>`_.


Installing GuessIt is simple with `pip <>`_::

$ pip install guessit

You can also `install GuessIt from sources <>`_


GuessIt can be used from command line::

$ guessit
usage: guessit [-h] [-t TYPE] [-n] [-Y] [-D] [-L ALLOWED_LANGUAGES]
[-a] [-j] [-y] [-p] [-V] [--version]
[filename [filename ...]]

positional arguments:
filename Filename or release name to guess

optional arguments:
-h, --help show this help message and exit

-t TYPE, --type TYPE The suggested file type: movie, episode. If undefined,
type will be guessed.
-n, --name-only Parse files as name only, considering "/" and "\" like
other separators.
-Y, --date-year-first
If short date is found, consider the first digits as
the year.
-D, --date-day-first If short date is found, consider the second digits as
the day.
Allowed language (can be used multiple times)
Allowed country (can be used multiple times)
-E, --episode-prefer-number
Guess "serie.213.avi" as the episode 213. Without this
option, it will be guessed as season 2, episode 13
Expected title to parse (can be used multiple times)
Expected release group (can be used multiple times)

-f INPUT_FILE, --input-file INPUT_FILE
Read filenames from an input text file. File should
use UTF-8 charset.

-v, --verbose Display debug output
Display the value of a single property (title, series,
video_codec, year, ...)
-a, --advanced Display advanced information for filename guesses, as
json output
-j, --json Display information for filename guesses as json
-y, --yaml Display information for filename guesses as yaml

-p, --properties Display properties that can be guessed.
-V, --values Display property values that can be guessed.
--version Display the guessit version.

It can also be used as a python module::

>>> from guessit import guessit
>>> guessit(u'Treme.1x03.Right.Place,.Wrong.Time.HDTV.XviD-NoTV.avi') # doctest: +ALLOW_UNICODE
MatchesDict([('title', 'Treme'), ('season', 1), ('episode', 3), ('episode_title', 'Right Place, Wrong Time'), ('format', '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.

GuessIt only accept unicode string, so you need to use ``u`` prefix for input string on python 2.


GuessIt is also available on `Docker Hub <>`_ as a Docker Image.::

$ docker run -it toilal/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",
"format": "HDTV",
"video_codec": "XviD",
"release_group": "NoTV",
"container": "avi",
"mimetype": "video/x-msvideo",
"type": "episode"


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.

GuessIt relies on `Rebulk <>`_ project for pattern and rules registration.


GuessIt is licensed under the `LGPLv3 license <>`_.


2.0rc7 (2016-01-18)

- Fix packaging issues on Python 2.7.

2.0rc6 (2016-01-18)

- Fix packaging issues.

2.0rc5 (2016-01-18)

- Guessit is now available as a docker container on Docker Hub (
- `country` 2-letter code is not added to `title` value anymore.
- All `container` values are now capitalized.
- `alternativeTitle` has been renamed to `alternative_title` and added to the docs.
- `mimetype` property is now in the docs.
- Add more excluded words for `language` property.
- Add more possible values for `other` property.
- Fix an issue occuring with `title` values starting with `Scr`.
- `film` property is now guessed only if less than `100` to avoid possible conflicts with `crc32`.

2.0rc4 (2015-12-03)

- Add docs.
- Add exotic `screen_size` patterns support like `720hd` and `720p50`.
- Rename `audio_codec` value `true-HD` to `trueHD`.

2.0rc3 (2015-11-29)

- Add ``__version__`` to main module.

2.0rc2 (2015-11-28)

- Single digit episodes are now guessed for ``--type episode`` instead of ``--episode-prefer-number``.
- Fix separators that could cause some titles to be splited with & and ;.
- Avoid possible ``NoneType`` error.

2.0rc1 (2015-11-27)

- Fallback to default title guessing when ``expected-title`` is not found.

2.0b4 (2015-11-24)

- Add ``expected-group`` option.
- Add validation rule for single digit ``episode`` to avoid false positives.
- Add ``verbose`` option.
- Fix ``expected-title`` option.
- Better unicode support in ``expected-group``/``expected-title`` option.

2.0b3 (2015-11-15)

- Add support for ``part`` with no space before number.
- Avoid ``uuid`` and ``crc32`` collision with ``season``/``episode`` properties.
- Add better space support for ``season``/``episode`` properties.
- Ensure ``date`` property is found when conflicting with ``season``/``episode`` properties.
- Fix ``IndexError`` when input has a closing group character with no opening one before.
- Add ``--type`` option.
- Add rebulk implicit option support.

2.0b2 (2015-11-14)

- Add python 2.6 support.

2.0b1 (2015-11-11)

- Enhance title guessing.
- Upgrade rebulk to ``0.6.1``.
- Rename ``properCount`` to ``proper_count``
- Avoid crash when using ``-p``/``-V`` option with ``--yaml`` and ``yaml`` module is not available.

2.0a4 (2015-11-09)

- Add ``-p``/``-V`` options to display properties and values that can be guessed.

2.0a3 (2015-11-08)

- Allow rebulk customization in API module.

2.0a2 (2015-11-07)

- Raise TypeError instead of AssertionError when non text is given to guessit API.
- Fix packaging issues with previous release blocking installation.

2.0a1 (2015-11-07)

- Rewrite from scratch using `Rebulk <>`_
- Read `MIGRATION.rst <>`_ for migration guidelines.

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for guessit, version 2.0rc7
Filename, size File type Python version Upload date Hashes
Filename, size guessit-2.0rc7.tar.gz (71.0 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page