---
id: subliminal
version: "2.7.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# subliminal — Subtitles, faster than your thoughts

License: permissive · Maintenance: active · Downloads: 106.7K/mo

## 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 above — verify before relying.

Subliminal downloads subtitles for video files from multiple online providers, available as both a command-line tool and a Python library.

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

pip install subliminal
uv add subliminal
poetry add subliminal

## Installing subliminal

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).

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])

Requires Python 3.10 or later. For best video metadata extraction, MediaInfo or another knowit provider should be installed separately.

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_current
- Install friction: low
- Maintenance: active
- Downloads: 106.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

download subtitles for videos, subtitle downloader, batch subtitle fetching, video subtitle automation, multi-language subtitle search, subtitle provider integration, CLI subtitle tool, video-automation, cli-tool, media-management

[View on SkillFed](https://skillfed.io/packages/subliminal) · [View on PyPI](https://pypi.org/project/subliminal/)