Release v0.7.5

Subliminal is a python library to search and download subtitles. It comes with an easy to use CLI suitable for direct use or cron jobs.


Subliminal uses multiple providers to give users a vast choice and have a better chance to find the best matching subtitles. Providers are extensible through a dedicated entry point.

  • Addic7ed
  • OpenSubtitles
  • Podnapisi
  • TheSubDB
  • TvSubtitles



Download english subtitles:

$ subliminal -l en -- The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
1 subtitle downloaded

See subliminal.cli


Download best subtitles in French and English for videos less than one week old in a video folder, skipping videos that already have subtitles whether they are embedded or not:

from babelfish import Language
from datetime import timedelta
import subliminal

# configure the cache
subliminal.cache_region.configure('dogpile.cache.dbm', arguments={'filename': '/path/to/cachefile.dbm'})

# scan for videos in the folder and their subtitles
videos = subliminal.scan_videos(['/path/to/video/folder'], subtitles=True, embedded_subtitles=True, age=timedelta(weeks=1))

# download
subliminal.download_best_subtitles(videos, {Language('eng'), Language('fra')}, age=timedelta(week=1))

See subliminal.api, scan_videos() and scan_video()

How it works

Subliminal makes use of various libraries to achieve its goal:

  • enzyme to detect embedded subtitles in videos and retrieve metadata
  • guessit to guess informations from filenames
  • babelfish to work with languages
  • requests to make human readable HTTP requests
  • BeautifulSoup to parse HTML and XML
  • dogpile.cache to cache intermediate search data
  • charade to detect subtitles’ encoding
  • pysrt to validate downloaded subtitles



API Documentation

If you are looking for information on a specific function, class or method, this part of the documentation is for you.



release date: 2015-03-04

  • Update requirements
  • Remove BierDopje provider
  • Add pre-guessed video optional argument in scan_video
  • Improve hearing impaired support
  • Fix TVSubtitles and Podnapisi providers


release date: 2014-01-27

  • Fix requirements for guessit and babelfish


release date: 2013-11-22

  • Fix windows compatibility
  • Improve subtitle validation
  • Improve embedded subtitle languages detection
  • Improve unittests


release date: 2013-11-10

  • Fix TVSubtitles for ambiguous series
  • Add a CACHE_VERSION to force cache reloading on version change
  • Set CLI default cache expiration time to 30 days
  • Add podnapisi provider
  • Support script for languages e.g. Latn, Cyrl
  • Improve logging levels
  • Fix subtitle validation in some rare cases


release date: 2013-11-06

  • Improve CLI
  • Add login support for Addic7ed
  • Remove lxml dependency
  • Many fixes


release date: 2013-10-29

WARNING: Complete rewrite of subliminal with backward incompatible changes

  • Use enzyme to parse metadata of videos
  • Use babelfish to handle languages
  • Use dogpile.cache for caching
  • Use charade to detect subtitle encoding
  • Use pysrt for subtitle validation
  • Use entry points for subtitle providers
  • New subtitle score computation
  • Hearing impaired subtitles support
  • Drop async support
  • Drop a few providers
  • And much more...


release date: 2012-09-15

  • Fix BierDopje
  • Fix Addic7ed
  • Fix SubsWiki
  • Fix missing enzyme import
  • Add Catalan and Galician languages to Addic7ed
  • Add possible services in help message of the CLI
  • Allow existing filenames to be passed without the ./ prefix


release date: 2012-06-24

  • Fix subtitle release name in BierDopje
  • Fix subtitles being downloaded multiple times
  • Add Chinese support to TvSubtitles
  • Fix encoding issues
  • Fix single download subtitles without the force option
  • Add Spanish (Latin America) exception to Addic7ed
  • Fix group_by_video when a list entry has None as subtitles
  • Add support for Galician language in Subtitulos
  • Add an integrity check after subtitles download for Addic7ed
  • Add error handling for if not strict in Language
  • Fix TheSubDB hash method to return None if the file is too small
  • Fix guessit.Language in Video.scan
  • Fix language detection of subtitles


release date: 2012-06-16 WARNING: Backward incompatible changes

  • Fix –workers option in CLI
  • Use a dedicated module for languages
  • Use beautifulsoup4
  • Improve return types
  • Add scan_filter option
  • Add –age option in CLI
  • Add TvSubtitles service
  • Add Addic7ed service


release date: 2012-03-25

  • Improve error handling of enzyme parsing


release date: 2012-03-25 WARNING: Backward incompatible changes

  • Use more unicode
  • New list_subtitles and download_subtitles methods
  • New Pool object for asynchronous work
  • Improve sort algorithm
  • Better error handling
  • Make sorting customizable
  • Remove class Subliminal
  • Remove permissions handling


release date: 2011-11-11

  • Many fixes
  • Better error handling


release date: 2011-08-18

  • Fix a bug when series is not guessed by guessit
  • Fix dependencies failure when installing package
  • Fix encoding issues with logging
  • Add a script to ease subtitles download
  • Add possibility to choose mode of created files
  • Add more checks before adjusting permissions


release date: 2011-07-11

  • Fix plugin configuration
  • Fix some encoding issues
  • Remove extra logging


release date: not released yet

  • Initial release