MPV can load a subtitle file beside your video, search a chosen subtitle folder, or run a Lua script that asks a subtitle provider for a match. If you need a shell refresher before running the commands, start with this Linux command-line walkthrough.
Choose the subtitle workflow you need
Use MPV’s built-in options for subtitle files you already keep with your videos, then add mpv-autosub only if local matching cannot handle the job.
| Need | Use |
|---|---|
| Load a file with the same name as the video | sub-auto=exact |
| Search a subtitle folder too | sub-file-paths |
| Request a download when no local match exists | mpv-autosub and Subliminal |
MPV’s sub-auto option controls how it matches external subtitle filenames. The exact mode is the safe default because it accepts a matching filename instead of loading every subtitle in the folder.[1]
Set up automatic local subtitle loading
Create your MPV configuration directory and open mpv.conf. If these paths are unfamiliar, review the Linux file system layout and the ways to edit a Linux file before changing the configuration.
mkdir -p ~/.config/mpv
nano ~/.config/mpv/mpv.conf
Add these settings when you store subtitles in a sub folder or a subtitles folder next to your media. MPV checks the video directory and these paths, then loads files that match the video name.
sub-auto=exact
sub-file-paths=sub:subtitles
For example, MPV can pair Film.mkv with Film.en.srt when both files are in the same directory. Change sub-auto to fuzzy only when your filenames include extra release details and you want MPV to accept them.[1]
Install mpv-autosub in its own environment
mpv-autosub calls the Subliminal command-line program. A Python virtual environment keeps that program and its libraries out of your system Python, then gives the Lua script one fixed executable path. See the Linux package-management primer if you need help separating system packages from language-specific tools.
python3 -m venv ~/.local/share/mpv-autosub-venv
~/.local/share/mpv-autosub-venv/bin/pip install --upgrade pip subliminal
~/.local/share/mpv-autosub-venv/bin/subliminal --help
The final command prints Subliminal’s command help when the installation is ready. That output confirms the executable that autosub.lua will invoke.
The screenshot below shows the older direct installation step from this post. Keep the virtual-environment command above for a new setup because it avoids changing the Python packages used by other tools.
Do not put provider passwords inside autosub.lua. If a subtitle provider requires an account, use that provider’s current account controls and keep any secret outside a shared script or repository.
Copy the script into MPV’s script directory
Clone the current mpv-autosub repository, then create MPV’s scripts directory. MPV automatically loads Lua files from ~/.config/mpv/scripts/ when it starts.[2][3]
git clone https://github.com/davidde/mpv-autosub
mkdir -p ~/.config/mpv/scripts
cp mpv-autosub/autosub.lua ~/.config/mpv/scripts/
The repository also offers a ZIP download for a manual installation, and the next screenshot shows the equivalent clone workflow.
Extract the archive before copying autosub.lua into MPV’s scripts directory because MPV selects the Lua scripting backend from the .lua extension.[3]
Point the script at Subliminal
Open the installed autosub.lua and set its subliminal variable to the virtual-environment executable. Nano works for this change, and the Vim exit commands are useful if you edit the file in Vim instead.
nano ~/.config/mpv/scripts/autosub.lua
local subliminal = '/home/your-user/.local/share/mpv-autosub-venv/bin/subliminal'
Replace your-user with your Linux username, then use the script’s language order, optional provider settings, download hotkeys, and location filters only after MPV loads it.[2]
The editor screenshot identifies the one line to change before you adjust optional settings.
Choose a hotkey that does not conflict with an MPV key binding you already use. The repository documents b and n as manual download keys for its first and second configured language.[2]
A provider account can improve access where the provider requires one, but the script file is the wrong place for a password that may be copied or backed up. Treat those credentials as provider-specific secrets.
Start MPV and check the result
Open a video with MPV after the script is in place. MPV loads scripts from its configuration directory at startup, and mpv-autosub downloads only when its automatic mode cannot find a subtitle already present.[2][3]
The next screenshot shows the script’s target result. If it does not appear, run the Subliminal help command again and confirm the executable path in autosub.lua points to your virtual environment.
Use a local subtitle file first when you only need a known SRT or ASS file. That route stays offline and gives you control over the file MPV loads.
Frequently asked questions
These checks separate MPV’s local subtitle matching from the optional downloader script.
Where does MPV load Lua scripts on Linux?
MPV loads Lua scripts from ~/.config/mpv/scripts/ by default. Put autosub.lua in that directory, then restart MPV.
How do I make MPV load local subtitle files automatically?
Add sub-auto=exact to ~/.config/mpv/mpv.conf. Add sub-file-paths=sub:subtitles when you also keep subtitle files in sub or subtitles folders.
Why does mpv-autosub not download subtitles?
Check that Subliminal is installed, run its help command, and make sure autosub.lua points to that exact executable path. Then restart MPV after saving the script.
Start with local matching in mpv.conf, then add mpv-autosub only when a provider download solves a problem your local subtitle files cannot.