Can mpv Auto-Load Subtitles with the Same Name?

By default, the mpv media player will automatically detect and load external subtitle files if they are located in the same directory and share the exact same filename as the video file. This feature eliminates the need to manually drag and drop subtitle tracks or browse through menus every time you open a video. This brief guide explains how this automatic loading works, how to configure mpv to scan additional folders (like a dedicated “subs” directory), and how to troubleshoot common matching issues.

How Exact Name Matching Works

If you have a video file named Movie.mp4, mpv looks for a subtitle file with the identical base name, such as Movie.srt or Movie.vtt, in the same folder. It also natively supports fuzzy matching, meaning it will recognize language tags appended to the end of the filename.

For example, if your video is Episode01.mkv, mpv will automatically load:

• Episode01.srt (Default track)
• Episode01.en.srt (English track)
• Episode01.es.srt (Spanish track)

Expanding Subtitle Search with Configuration

If your subtitle files are stored in a subfolder rather than alongside the video, you can instruct mpv to search for them by editing your mpv.conf file.

Adjusting the Search Path

Add the sub-file-paths option to your configuration file to specify where mpv should look for matching external subtitles. A common setup includes looking in folders named subs, subtitles, or srt:

sub-file-paths=sub:subtitles:srt

Changing the Matching Strictness

You can control how aggressively mpv searches for subtitles using the sub-auto setting. Add one of the following lines to your mpv.conf depending on your preference:

• sub-auto=exact (Default): Loads external subtitles only if they match the video filename exactly (with or without language extensions).
• sub-auto=fuzzy: Loads all subtitles containing the video filename anywhere in their name.
• sub-auto=all: Automatically loads all subtitle files found in the current video directory and specified sub-file paths, regardless of their names.

Troubleshooting Common Issues

If your external subtitles are not loading automatically, check the following culprits:

• Spelling and Case Sensitivity: Ensure there are no typos, extra spaces, or mismatched casing between the video file and the subtitle file.
• File Extensions: Verify that file extensions are not hidden by your operating system (e.g., a file named Movie.srt.txt will fail to load properly).
• Configuration Location: Ensure your mpv.conf is placed in the correct directory for your operating system (usually ~/.config/mpv/ on Linux/macOS or %APPDATA%\mpv\ on Windows).