# Install subliminal with Homebrew, apk, apt, zypper

Library to search and download subtitles. Version 2.6.0 via Homebrew; verified 2026-05-14.

## 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 python3-subliminal
```

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

- zypper (92%):

```sh
sudo zypper install python311-subliminal
```

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

## Package facts

- **Package key:** brew:subliminal
- **Package manager:** Homebrew
- **Package manager page:** <https://formulae.brew.sh/formula/subliminal>
- **Version:** 2.6.0
- **Source summary:** Library to search and download subtitles
- **Homepage:** <https://subliminal.readthedocs.io>
- **Repository:** <https://github.com/Diaoul/subliminal>
- **Upstream docs:** <https://subliminal.readthedocs.io/en/latest>
- **License:** MIT
- **Source archive:** <https://files.pythonhosted.org/packages/56/05/3529ed61f1471fe7c01a6a14183e21c12f3ae09dc79f796962a484d91f28/subliminal-2.6.0.tar.gz>
- **Last updated:** 2026-05-14T12:57:33Z
- **Generated:** 2026-07-08T07:18:31+00:00

## Executables

- subliminal (cli)
- subliminal (alias)

## Dependencies

- certifi
- libyaml
- python@3.14

## Install behavior

- Post-install hook: not defined
- Bottle: available on arm64_linux, arm64_sequoia, arm64_sonoma, arm64_tahoe, sonoma, x86_64_linux

## Freshness

- Page generated: 2026-07-08
- Package-manager version: 2.6.0
- Package-manager updated: 2026-05-14
- Local data: ok
- Upstream repository: https://subliminal.readthedocs.io
- info: Release/tag comparison is only available for GitHub repositories.
## 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
## Source Database Details

- **Source Database:** Homebrew formula API
- **Tap:** homebrew/core
- **Full Name:** subliminal
- **Version Scheme:** 0
- **Revision:** 2
- **Head Version:** HEAD
- **Bottle Stable Root URL:** <https://ghcr.io/v2/homebrew/core>
- **Deprecated:** no
- **Disabled:** no
- **Keg Only:** no
- **URL Keys:** head, stable

## 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 - python311-subliminal - 2.6.0-1.3: normalized package name match | openSUSE Tumbleweed package metadata: python311-subliminal from https://download.opensuse.org/tumbleweed/repo/oss/repodata/be8d3611d25469107f32075a1697e69ec57a2b850b42348a658cc671ad5ec2b50760d02c3e59524d50da9a11d5be799bdaffba2e166e8ca8858512e3c0bd665d-primary.xml.zst | Python library to search and download subtitles | https://github.com/Diaoul/subliminal
- zypper - python313-subliminal - 2.6.0-1.3: normalized package name match | openSUSE Tumbleweed package metadata: python313-subliminal from https://download.opensuse.org/tumbleweed/repo/oss/repodata/be8d3611d25469107f32075a1697e69ec57a2b850b42348a658cc671ad5ec2b50760d02c3e59524d50da9a11d5be799bdaffba2e166e8ca8858512e3c0bd665d-primary.xml.zst | Python library to search and download subtitles | https://github.com/Diaoul/subliminal
- zypper - python314-subliminal - 2.6.0-1.3: normalized package name match | openSUSE Tumbleweed package metadata: python314-subliminal from https://download.opensuse.org/tumbleweed/repo/oss/repodata/be8d3611d25469107f32075a1697e69ec57a2b850b42348a658cc671ad5ec2b50760d02c3e59524d50da9a11d5be799bdaffba2e166e8ca8858512e3c0bd665d-primary.xml.zst | Python library to search and download subtitles | https://github.com/Diaoul/subliminal


## Related links

- [Terminal utility packages](https://www.automicvault.com/pkg/terminal-utilities/) - Matched terminal and command-line workflow metadata.
- [Text processing packages](https://www.automicvault.com/pkg/text-processing-tools/) - Matched text, document, or structured-data processing metadata.
- [Language runtime packages](https://www.automicvault.com/pkg/language-runtime-packages/) - Matched language runtime, compiler, or interpreter metadata.
- [Networking and protocol packages](https://www.automicvault.com/pkg/networking-protocol-tools/) - Matched network, protocol, or remote-service metadata.
- [python@3.14](https://www.automicvault.com/pkg/brew/python-3-14/) - Runtime dependency declared by Homebrew.
- [alass](https://www.automicvault.com/pkg/brew/alass/) - Shares av.db curated category or tags: cli, media, subtitles.
- [ccextractor](https://www.automicvault.com/pkg/brew/ccextractor/) - Shares av.db curated category or tags: cli, media, subtitles.
- [moribito](https://www.automicvault.com/pkg/brew/moribito/) - Shares av.db curated category or tags: cli, media, subtitles.
- [sub2srt](https://www.automicvault.com/pkg/brew/sub2srt/) - Shares av.db curated category or tags: cli, media, subtitles.
- [bandcamp-dl](https://www.automicvault.com/pkg/brew/bandcamp-dl/) - Shares av.db curated category or tags: cli, download, media, python.
- [a52dec](https://www.automicvault.com/pkg/brew/a52dec/) - Shares av.db curated category or tags: cli, library, media.
- [aalib](https://www.automicvault.com/pkg/brew/aalib/) - Shares av.db curated category or tags: cli, library, media.
- [adplug](https://www.automicvault.com/pkg/brew/adplug/) - Shares av.db curated category or tags: cli, library, media.
- [svtplay-dl](https://www.automicvault.com/pkg/brew/svtplay-dl/) - Both packages touch the same language runtime or ecosystem. Shared terms: certifi, cli, download, libyaml, media.
- [bilix](https://www.automicvault.com/pkg/brew/bilix/) - Both packages touch the same language runtime or ecosystem. Shared terms: certifi, cli, download, media, python.

## Combined YAML source

View the package source record on GitHub. [combined/subliminal.yml](https://github.com/automic-vault/db/blob/main/combined/subliminal.yml)


## Sources

- Nucleus package database
- Geiger risk classifier
- package-page enrichment
- curated configuration and credential file locations
- curated package history
- package version freshness
- av.db category and tag curation
- package relationship graph
- external package-manager database matches
- cross-ecosystem install command graph