Subtitles, faster than your thoughts.
- Project page:
- Documentation:
- Community:
Usage
CLI
Download English subtitles:
$ subliminal download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4 Collecting videos [####################################] 100% 1 video collected / 0 video ignored / 0 error Downloading subtitles [####################################] 100% Downloaded 1 subtitle
Configuration
Arguments can be passed to the CLI using a configuration file. By default it looks for a subliminal.toml file in the default configuration folder (see the CLI help for the exact platform-specific default path). Or use the -c option to specify the path to the configuration file.
Look for this example configuration file or use the generate_default_config function from the subliminal.cli module to generate a configuration file with all the options and their default values:
$ python -c "from subliminal.cli import generate_default_config; print(generate_default_config())"
Library
Download best subtitles in French and English for videos less than two weeks old in a video folder:
#!/usr/bin/env python
from datetime import timedelta
from babelfish import Language
from subliminal import download_best_subtitles, region, save_subtitles, scan_videos
# configure the cache
region.configure('dogpile.cache.dbm', arguments={'filename': 'cachefile.dbm'})
# scan for videos newer than 2 weeks and their existing subtitles in a folder
videos = scan_videos('/video/folder', age=timedelta(weeks=2))
# download best subtitles
subtitles = download_best_subtitles(videos, {Language('eng'), Language('fra')})
# save them to disk, next to the video
for v in videos:
save_subtitles(v, subtitles[v])Docker
Run subliminal in a docker container:
$ docker run --rm --name subliminal -v subliminal_cache:/usr/src/cache -v /tvshows:/tvshows -it ghcr.io/diaoul/subliminal download -l en /tvshows/The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
Debugging
By default, subliminal output is minimal. Run with the –debug flag before the download command to get more information:
$ subliminal --debug download -l en The.Big.Bang.Theory.S05E18.HDTV.x264-LOL.mp4
Installation
For a better isolation with your system you should use a dedicated virtualenv. The preferred installation method is to use pipx that does that for you:
$ pipx install subliminal
Subliminal can be also be installed as a regular python module by running:
$ pip install --user subliminal
If you want to modify the code, fork this repo, clone your fork locally and install a development version:
$ git clone https://github.com/<my-username>/subliminal $ cd subliminal $ pip install --user -e '.[docs,types,tests,dev]'
To extract information about the video files, subliminal uses knowit. For better results, make sure one of its provider is installed, for instance MediaInfo.
Integrations
Subliminal integrates with various desktop file managers to enhance your workflow:
Nautilus/Nemo: See the dedicated project page for more information.
Dolphin: See this Gist. for more details.
Contributing
We welcome contributions from the community! If you’re interested in contributing, here are a few ways you can get involved:
Browse Issues and Pull Requests: Check out the existing Issues and Pull Requests to see where you can help.
Report Bugs or Request Features: If you encounter a bug or have a feature request, please create a GitHub Issue.
Follow the Contribution Guide: For detailed instructions on how to contribute, please refer to our Contribution Guide.
Your contributions are greatly appreciated and help make this project better for everyone!
Release files for subliminal 2.7.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| subliminal-2.7.1.tar.gz | 4.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| subliminal-2.7.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 4.1 MB
Release files / subliminal-2.7.1.tar.gz
| Download URL | subliminal-2.7.1.tar.gz |
|---|---|
| Size | 4.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f2649914d3067904effa2b4ce8d83aae994cd47008253311d5ae7949f467939f
|
|
BLAKE2b-256 checksum How to use checksums |
9f08f602bac8c35f04021e6dfcd0bebea917cd2b57116229a74a0b97e63c72ab
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 23, 2026.
Transparency logRelease files / subliminal-2.7.1-py3-none-any.whl
| Download URL | subliminal-2.7.1-py3-none-any.whl |
|---|---|
| Size | 123.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a52db51fde5fbe3f7d3afa6c939bd4337a1ede610c701ee1d89a6f7a066ecd80
|
|
BLAKE2b-256 checksum How to use checksums |
5f63a47a01fc3387963c28507050f7d8212a6c00fa49fcb5f5a96f6877441460
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 23, 2026.
Transparency log
