subliminal
Subtitles, faster than your thoughts
Decision gist · record as of 2026-08-14
Yes. Subliminal is actively maintained, has no known vulnerabilities, installs cleanly, and solves a real problem for anyone managing video libraries. The dual CLI and library interface makes it useful both as a standalone tool and as a component in larger workflows. The MIT license poses no restrictions. Install it if you regularly need to download subtitles for video files.AI-flagged interpretation of the facts on this page — verify before relying
Before you install
- Requires Python 3.10 or later.
- For best video metadata extraction, MediaInfo or another knowit provider should be installed separately.
- Low install friction with a pure-Python wheel distribution.
License · maintenance · safety
MIT (permissive) — MIT license is permissive and imposes no significant restrictions on use, modification, or distribution in proprietary or open-source projects.
last release 2026-07-23 (22 days) · last repo commit 2026-07-23 · 2,656 stars
0 known vulnerabilities (OSV.dev, 2026-08-14) · 106,705 downloads/mo, #12,644 on PyPI
Alternatives
Verify before relying
pip install subliminal
from subliminal import download_best_subtitles, scan_videos, save_subtitles
from babelfish import Language
videos = scan_videos('/path/to/videos')
subtitles = download_best_subtitles(videos, {Language('eng')})
for v in videos:
save_subtitles(v, subtitles[v])- Which subtitle providers are currently supported and whether any require API keys or authentication.
- Whether the package handles DRM-protected or region-locked subtitle sources.
- Performance characteristics when scanning and downloading subtitles for large video libraries.
What it is and what it does
Subliminal is a subtitle downloader that searches multiple online providers to find and download subtitles for video files. It works both as a standalone command-line tool and as a Python library, making it suitable for one-off downloads or integration into larger media management workflows. The package uses guessit and knowit to extract video metadata (title, season, episode, release group) to improve search accuracy, and caches results to avoid redundant lookups.
The library depends on a broad set of utilities: beautifulsoup4 and requests for web scraping, chardet for encoding detection, babelfish for language handling, pysubs2 and srt for subtitle format support, and stevedore for plugin-based provider discovery. It includes configuration file support via TOML and integrates with desktop file managers on Linux (Nautilus, Nemo, Dolphin).
Use it for
- Batch download subtitles for a TV series folder in multiple languages via CLI with a single command.
- Integrate subtitle fetching into a media server or home theater PC setup using the Python library API.
- Automatically download subtitles for newly added videos using cron or a media library watcher.
- Extract and cache subtitle metadata to avoid repeated provider queries across multiple runs.
- Extend subtitle provider support by writing custom provider plugins via the stevedore plugin system.
Worth the install?
AI-flagged interpretation of the facts on this page. Verify before relying on it.
Yes.
Subliminal is actively maintained, has no known vulnerabilities, installs cleanly, and solves a real problem for anyone managing video libraries. The dual CLI and library interface makes it useful both as a standalone tool and as a component in larger workflows. The MIT license poses no restrictions. Install it if you regularly need to download subtitles for video files.
Install
subliminal on PyPI
Before you install
Low install friction with a pure-Python wheel distribution. Active maintenance with a recent release (22 days old) and steady repository activity. Depends on 15 runtime packages including web scraping (beautifulsoup4, requests), language detection (chardet, babelfish), and video metadata extraction (knowit, guessit).
Requires Python 3.10 or later. For best video metadata extraction, MediaInfo or another knowit provider should be installed separately.
License in practice
MIT license is permissive and imposes no significant restrictions on use, modification, or distribution in proprietary or open-source projects.
Quickstart
pip install subliminal
from subliminal import download_best_subtitles, scan_videos, save_subtitles
from babelfish import Language
videos = scan_videos('/path/to/videos')
subtitles = download_best_subtitles(videos, {Language('eng')})
for v in videos:
save_subtitles(v, subtitles[v])Verify before relying
- Which subtitle providers are currently supported and whether any require API keys or authentication.
- Whether the package handles DRM-protected or region-locked subtitle sources.
- Performance characteristics when scanning and downloading subtitles for large video libraries.
Package facts
| License | MIT permissive |
| Python support | Supports the current Python release >=3.10 |
| Install friction | Low. Pure-Python wheel |
| Runtime dependencies | 15 packagesbabelfishbeautifulsoup4chardetclickclick-option-groupdefusedxmldogpile-cacheguessitknowitplatformdirspysubs2requestssrtstevedoretomlkit |
| Maintenance | Actively maintained 22 days since the last release |
| Last repo commit | |
| First released | |
| Downloads | 106,705 / month, #12,644 on PyPI 30-day window, as of 2026-08-14 |
| Known vulnerabilities | None known OSV.dev, checked 2026-08-14 |
| Classifiers | Development Status :: 5 - Production/StableIntended Audience :: DevelopersLicense :: OSI Approved :: MIT LicenseOperating System :: OS IndependentProgramming Language :: PythonProgramming Language :: Python :: 3Programming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Topic :: Multimedia :: VideoTopic :: Software Development :: Libraries :: Python Modules |
Evidence: subliminal-2.7.1-py3-none-any.whl
Tags
Let your AI agent find packages like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 14,416 PyPI packages by what they can do, searchable in plain language.
wish › “download subtitles for videos”
- subliminalSubliminal downloads subtitles for video files from multiple online…
- youtube-transcript-apiFetches transcripts and subtitles from YouTube videos via API,…
- pytubefixDownloads YouTube videos, playlists, and channels in multiple formats…
Give your agent the search over MCP, or paste the wish link into any chat.
More Python Modules packages
Converts domain names between Unicode and ASCII-compatible encoding (Punycode) according to IDNA 2008 and Unicode Technical Standard 46, with security validation and broader script coverage than the standard library.
Install it if you work with internationalized domain names, need to validate domains, or use HTTP clients that depend on it transitively.
Setuptools is a Python build backend and package management tool that handles building, distributing, and installing Python packages, including support for C/C++ extension modules.
PyYAML parses and emits YAML 1.1 data format, enabling serialization and deserialization of configuration files and Python objects to and from human-readable YAML text.
Pydantic validates Python data structures against type hints, coercing and checking input at runtime to ensure it matches a declared schema.
Provides reusable metadata objects for use with PEP-593 `typing.Annotated` to express common constraints like bounds, collection sizes, and predicates on types.
Install it if you use or build libraries that need to express type constraints in a standardized, inspectable way—or if you want to annotate your own types with…
Provides runtime tools to inspect and introspect Python type annotations, enabling programmatic examination of type hints at execution time.
See also youtube-transcript-api · pysubs2 · pytube · youtube_dl · pytubefix · knowit · edge-tts · pysrt · trakit · scenedetect