# Install subliminal with Homebrew, apk, apt, zypper

Library to search and download subtitles. Version 2.7.1 via Homebrew; verified 2026-07-24. Also installable with debian: sudo apt install python3-subliminal.

## Install

```sh
sudo av install brew:subliminal
```

Additional install commands:

### macOS

- Homebrew (100%):

```sh
brew install subliminal
```

  Evidence: local Homebrew formula metadata

### Linux

- apk (92%):

```sh
sudo apk add subliminal
```

  Evidence: Alpine Linux edge package indexes: subliminal from https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz

- Debian apt (92%):

```sh
sudo apt install subliminal
```

  Evidence: Debian stable package indexes: subliminal from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz

- zypper (92%):

```sh
sudo zypper install python313-subliminal
```

  Evidence: openSUSE Tumbleweed package metadata: python313-subliminal from https://download.opensuse.org/tumbleweed/repo/oss/repodata/50b07339cb64c8ed4091bdbabddadc1ff5737b090e478818a195b40d8a3292861a879139b4a3987c31109699fde9fbf4a716367ddf4eef77da75f96e3193d6ed-primary.xml.zst

## Package facts

- **Package key:** brew:subliminal
- **Package manager:** Homebrew
- **Version:** 2.7.1
- **Source summary:** Library to search and download subtitles
- **Homepage:** <https://subliminal.readthedocs.io>
- **Repository:** <https://github.com/Diaoul/subliminal>
- **Last updated:** 2026-07-24T05:08:49Z
- **Generated:** 2026-08-03T19:37:03+00:00

## Executables

- subliminal (alias)

## Install behavior

- Bottle: not available

## Freshness

- Page generated: 2026-08-03
- Package-manager version: 2.7.1
## Project history and usage

Subliminal is a Python library and command-line program for finding and downloading subtitles for video files. In package-manager culture it sits in the small but useful class of media automation tools: something installed with Homebrew, Debian, or another OS package manager so media-library scripts can call a stable `subliminal` executable.

### Project history

The official changelog shows Subliminal as an established Python project by the early 2010s, with 0.2 released in July 2011 and a 0.7 rewrite in October 2013. The modern documentation presents both a CLI and a library API, reflecting the project's two audiences: shell users who want subtitle files beside videos, and Python users who want provider/refiner/scoring logic inside a larger application.

### Adoption history

The Homebrew input records Subliminal packages across Homebrew, Debian, Ubuntu, Alpine, and openSUSE-family package managers. That spread is typical for small Python CLI utilities that are useful to media servers, NAS setups, and cron-driven home automation.

### How it is used

The official usage guide centers on `subliminal download -l en <video>`, with options for languages, providers, refiners, age filters, output directory, cache management, and TOML configuration. The docs explicitly warn cron users to restrict searches by age to avoid abusing subtitle providers.

### Why package nerds care

Package nerds care about Subliminal because it turns a fragile web task into a repeatable CLI/API dependency with provider plugins, cache behavior, config-file support, and distro packages. It is also a good example of why package managers carry niche media tools: the package is small, but the workflow is exactly the kind of thing users want to script.

### Timeline

- 2011: Version 0.2 appears in the official changelog.
- 2013: Version 0.7 is described as a complete rewrite.
- 2016: The Read the Docs build identifies Antoine Bertin copyright and Sphinx documentation.
- 2026: GitHub tags show continued 2.x maintenance.

### Related projects

- The official CLI documents providers such as OpenSubtitles, OpenSubtitles.com, Podnapisi, Addic7ed, NapiProjekt, and TVSubtitles, plus refiners such as metadata, OMDB, TMDB, and TVDB.

### Sources

- Input package-manager data: source_facts.package-manager
- Official CLI docs: https://subliminal.readthedocs.io/en/latest/user/cli.html
- Official docs: https://subliminal.readthedocs.io/en/latest/user/usage.html
- Official repository/tags: https://github.com/Diaoul/subliminal


## Security Notes

No matching local secret-handling manifest was found for subliminal. Nucleus package metadata is still published here so future coverage has a stable package URL.



## Configuration and credential file locations

These source-backed paths show where this package keeps local settings or durable credentials. Automic Vault can use them as review targets for secret scanning, migration, and command approval.


## Configuration files

- Linux: ~/.config/subliminal/subliminal.toml
- macOS: ~/Library/Application Support/subliminal/subliminal.toml
- Windows: %LOCALAPPDATA%\Acme\subliminal\subliminal.toml

## Credential files

- Linux: ~/.config/subliminal/subliminal.toml
- macOS: ~/Library/Application Support/subliminal/subliminal.toml
- Windows: %LOCALAPPDATA%\Acme\subliminal\subliminal.toml
## Other Package-Manager Records

- Debian apt - python3-subliminal - 2.2.0-1: normalized package name match | Debian stable package indexes: python3-subliminal from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz | Python library to search and download subtitles (python3 version) | https://github.com/Diaoul/subliminal
- Debian apt - subliminal - 2.2.0-1: normalized package name match | Debian stable package indexes: subliminal from https://deb.debian.org/debian/dists/stable/main/binary-amd64/Packages.xz | Command-line tool to search and download subtitles | https://github.com/Diaoul/subliminal
- Ubuntu apt - python3-subliminal - 2.1.0-3: normalized package name match | Ubuntu 24.04 LTS package indexes: python3-subliminal from https://archive.ubuntu.com/ubuntu/dists/noble/universe/binary-amd64/Packages.gz | Python library to search and download subtitles (python3 version) | https://github.com/Diaoul/subliminal
- Ubuntu apt - subliminal - 2.1.0-3: normalized package name match | Ubuntu 24.04 LTS package indexes: subliminal from https://archive.ubuntu.com/ubuntu/dists/noble/universe/binary-amd64/Packages.gz | Command-line tool to search and download subtitles | https://github.com/Diaoul/subliminal
- apk - subliminal - 2.6.0-r1: normalized package name match | Alpine Linux edge package indexes: subliminal from https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz | Python library and CLI tool for searching and downloading subtitles | https://github.com/Diaoul/subliminal
- apk - subliminal-pyc - 2.6.0-r1: normalized package name match | Alpine Linux edge package indexes: subliminal-pyc from https://dl-cdn.alpinelinux.org/alpine/edge/testing/x86_64/APKINDEX.tar.gz | Precompiled Python bytecode for subliminal | https://github.com/Diaoul/subliminal
- zypper - python313-subliminal - 2.7.1-1.1: normalized package name match | openSUSE Tumbleweed package metadata: python313-subliminal from https://download.opensuse.org/tumbleweed/repo/oss/repodata/50b07339cb64c8ed4091bdbabddadc1ff5737b090e478818a195b40d8a3292861a879139b4a3987c31109699fde9fbf4a716367ddf4eef77da75f96e3193d6ed-primary.xml.zst | Python library to search and download subtitles | https://github.com/Diaoul/subliminal
- zypper - python314-subliminal - 2.7.1-1.1: normalized package name match | openSUSE Tumbleweed package metadata: python314-subliminal from https://download.opensuse.org/tumbleweed/repo/oss/repodata/50b07339cb64c8ed4091bdbabddadc1ff5737b090e478818a195b40d8a3292861a879139b4a3987c31109699fde9fbf4a716367ddf4eef77da75f96e3193d6ed-primary.xml.zst | Python library to search and download subtitles | https://github.com/Diaoul/subliminal


## Combined YAML source

View the package source record on GitHub. [combined/subliminal.yml](https://github.com/mxcl/pkgdb/blob/main/combined/subliminal.yml)


## Sources

- pkg.so package database
- Geiger risk classifier
- curated configuration and credential file locations
- curated package history
- pkgdb category and tag curation
- external package-manager database matches
- cross-ecosystem install command graph