mpv Subtitle File Auto Detection Not Working: How to Fix It

When mpv subtitle file auto detection is not working, the usual symptom is simple: a video and subtitle file are stored in the same folder, but mpv plays the video without loading the subtitle track. The most likely causes are filename matching, the --sub-auto mode, an incomplete subtitle search path, a profile or script overriding subtitle settings, or filesystem access problems. The fastest troubleshooting method is to prove that mpv can open the subtitle explicitly, repeat the test with a clean configuration, and then restore custom settings one group at a time.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing mpv.conf, changing hardware decoding, or reinstalling anything, determine whether this is an automatic discovery failure or a subtitle decoding failure. Those are different problems and require different fixes.

1.1 Test the subtitle file explicitly

Start by loading the external subtitle with --sub-file. Use absolute paths where possible so the test does not depend on the shell's current directory.

On Linux or macOS, run a command similar to:

mpv --no-config --sub-file="/path/to/Movie.en.srt" "/path/to/Movie.mkv"

In Windows PowerShell or Command Prompt, use the appropriate executable name and quote both paths:

mpv.exe --no-config --sub-file="C:\Media\Movie.en.srt" "C:\Media\Movie.mkv"

If the subtitle appears and can be selected, mpv can read and parse the file. The failure is specifically automatic discovery, so stop investigating codecs, GPU drivers, HDR output, hardware decoding, or audio backends. Those components do not normally decide whether a neighboring subtitle file is discovered.

If explicit loading fails, read the terminal error. Check whether the path exists, the extension is correct, the file is readable, and the subtitle format is supported. An empty, malformed, compressed, or incorrectly named file may look like a discovery problem even when it is not.

1.2 Test automatic discovery without your configuration

Place a video and subtitle in one test directory and give them identical base names:

• Movie.mkv
• Movie.srt

Then run:

mpv --no-config --sub-auto=exact "/path/to/Movie.mkv"

Success means the subtitle is listed as an external track and is displayed or available through subtitle track selection. Once this works, stop changing operating system or mpv installation settings. The remaining problem is almost certainly in your normal configuration, filename convention, search paths, profile selection, or scripts.

If exact matching does not work, try:

mpv --no-config --sub-auto=all "/path/to/Movie.mkv"

The all mode is useful diagnostically because it relaxes filename matching. Do not treat it as the only permanent solution in a folder containing subtitles for many unrelated videos.

2. Check Subtitle Discovery Options and Configuration Overrides

mpv can receive options from command-line arguments, global and user configuration files, profiles, scripts, and launchers. A setting that looks correct in one file may be replaced later by another source.

2.1 Understand the available sub-auto values

The --sub-auto option controls automatic loading of external subtitle files. Its relevant values are:

• no: disables automatic external subtitle discovery
• exact: uses strict matching based on the video filename
• fuzzy: allows broader filename matching and is mpv's normal default behavior
• all: loads subtitle candidates without requiring the video filename to match

If your configuration contains sub-auto=no, files in the same folder will not be discovered automatically. Change it to sub-auto=fuzzy for common naming conventions or sub-auto=exact if you want conservative matching.

Use all carefully. In a directory containing many videos and subtitles, it can make unrelated tracks available. It is better as a temporary test or for tightly controlled per-title directories.

2.2 Check exact and fuzzy filename matching

For the most reliable result, use the same base name for the video and subtitle:

• Episode 01.mkv with Episode 01.srt
• Film.2024.mp4 with Film.2024.ass

Fuzzy matching is useful when the subtitle includes additional identifying text, such as a language code or release label. However, matching becomes less predictable when the video and subtitle names differ substantially.

A weak pair would be My Film Final.mkv and English corrected subtitles.srt. Rename the subtitle to something based on the video's full base name, such as My Film Final.en.srt.

After renaming, replay the file with --no-config --sub-auto=fuzzy. If the subtitle now appears, filename matching was the cause. Stop there unless you need to standardize more filenames.

2.3 Use subtitle language suffixes consistently

Language suffixes help distinguish multiple external tracks. Common examples include:

• Movie.en.srt
• Movie.eng.srt
• Movie.es.ass
• Movie.ja.srt
• Movie.en.forced.srt

Keep the complete video base name at the beginning. A suffix does not guarantee that a track will be selected for display because discovery and selection are separate stages. Options such as slang, sid, or subtitle visibility can affect which discovered track is active.

If the track appears in mpv's track list but is not displayed, auto-detection succeeded. Select the subtitle track manually and review language preferences or track-selection settings rather than changing sub-auto.

2.4 Review sub-file-paths

Subtitles do not have to be in the video's directory. The sub-file-paths option tells mpv to search additional locations. A typical configuration for a subdirectory is:

sub-file-paths=subs

This can be useful for a structure such as:

• Movie.mkv
• subs/Movie.en.srt

Relative search paths are interpreted in mpv's applicable file context, so test an absolute path if a relative path behaves unexpectedly. Path-list separators and escaping can vary by operating system and configuration syntax. When testing multiple directories, consult the current mpv manual and avoid assuming that a Windows separator works unchanged on Linux or macOS.

If a subtitle is found with an absolute sub-file-paths value but not a relative one, the issue is path resolution. Keep the working absolute path or correct the relative directory layout.

2.5 Inspect profiles and launch-time options

A profile can override a global subtitle setting. For example, your main configuration may specify sub-auto=fuzzy, while a profile used for local files contains sub-auto=no. Auto profiles, protocol profiles, file-extension profiles, and options supplied by a GUI launcher can also change the final behavior.

List known profiles with:

mpv --profile=help

Inspect a particular profile with:

mpv --show-profile=PROFILE_NAME

Look for sub-auto, sub-file-paths, sid, slang, or options that disable subtitle visibility. Also search your configuration files for repeated subtitle options. The effective result matters more than the first occurrence you find.

2.6 Separate discovery from subtitle selection

A discovered subtitle can remain invisible because subtitle display is disabled or another track was selected. Check the track list in the on-screen controller or stats interface. Depending on your bindings and mpv build, the built-in stats overlay is commonly available with i.

These outcomes mean different things:

• The external track is absent: continue investigating discovery, paths, matching, permissions, or scripts
• The external track is present but inactive: review track selection and language preferences
• The external track is active but no text appears: check subtitle timing, file contents, styling, and encoding

Do not change video output, HDR tone mapping, shaders, or hwdec merely because a discovered subtitle is not selected. Those settings address different playback stages.

3. Check File Paths, Permissions, and Media Limitations

Operating system and path problems become relevant when explicit loading fails, a subtitle search directory cannot be accessed, or behavior changes depending on how mpv is launched.

3.1 Quote every path containing spaces

Shell parsing can split an unquoted path into multiple arguments. Always quote video, subtitle, configuration, and log paths containing spaces. This is especially important in scripts, custom input bindings, desktop launchers, and wrapper commands.

Also confirm that the filename does not contain a misleading double extension, such as Movie.srt.txt. File managers may hide known extensions, making the file appear to be an SRT when it is actually plain text with a final TXT extension.

3.2 Confirm filesystem access

Verify that the account running mpv can read both the video directory and subtitle file. On Linux and macOS, inspect file and directory permissions. On Windows, check whether the file is available to the current user and whether controlled folder access, network share credentials, or sandboxing affects the launcher.

For network-mounted directories, confirm the mount is active and that filenames are visible from the same environment that launches mpv. A media library visible in a graphical file manager may not be mounted identically inside a sandboxed application.

3.3 Distinguish local files from streams and online URLs

Same-folder discovery applies naturally to local media files because mpv has a filesystem directory to search. An HTTP stream, playlist URL, network stream, or URL handled through yt-dlp does not necessarily have a meaningful neighboring local directory.

If you play an online URL and want a local subtitle, specify it explicitly with --sub-file. Do not troubleshoot the yt-dlp path, network access, or stream extractor unless opening the media URL itself fails. If the stream plays but a local subtitle is absent, test the local subtitle explicitly first.

Similarly, embedded subtitles inside MKV or MP4 containers are not external auto-discovery candidates. They are tracks within the media file and should be investigated through track selection.

3.4 Know which settings are unrelated

GPU drivers, display servers, video output drivers, audio backends, HDR settings, shaders, and hardware decoders can affect rendering or playback stability. They do not ordinarily control whether mpv scans a directory for an SRT or ASS file.

Screenshot options, IPC settings, input bindings, playlists, and high-bitrate decoding are also unrelated unless a custom script or binding actively changes subtitle properties. Keep the investigation narrow to avoid introducing a second mpv player issue while fixing the first.

4. Use Logs and Runtime Information to Find the Override

If the clean test works but normal playback does not, diagnostic output can reveal loaded configuration files, applied profiles, script activity, and subtitle-related errors.

4.1 Create a verbose log

Run the affected file with a log:

mpv --msg-level=all=v --log-file=mpv-subtitles.log "/path/to/Movie.mkv"

Reproduce the problem, close mpv, and search the log for terms such as sub, subtitle, profile, config, and the subtitle filename. Avoid publishing the complete log without reviewing it because paths, URLs, usernames, or network details may be private.

Compare this with a clean run:

mpv --no-config --sub-auto=fuzzy --msg-level=all=v --log-file=mpv-clean.log "/path/to/Movie.mkv"

If the clean log shows the external track while the normal log does not, compare configuration and script loading rather than reinstalling mpv.

4.2 Inspect the track list and stats overlay

The track list is the clearest dividing line between discovery and display. If it lists an external subtitle with the expected filename, mpv found it. At that point, investigate subtitle selection, language priority, visibility, delay, or the subtitle's actual timing.

If the track is missing, focus on sub-auto, filename matching, sub-file-paths, permissions, and configuration overrides. The stats overlay can provide useful playback context, but terminal logs are generally better for identifying discovery decisions.

4.3 Temporarily disable scripts

The --no-config test bypasses normal user configuration and is the safest first isolation step. If you need finer isolation, temporarily launch mpv without user scripts or move only the suspected script out of its scripts directory. Do not delete the entire configuration folder.

Scripts may set properties at startup, process file-loaded events, or alter track selection. Input bindings can also call commands that remove, cycle, or disable subtitle tracks. Restore components one at a time until the failure returns.

5. Run a Clean Temporary Test Before Making Permanent Changes

A controlled test prevents several simultaneous edits from hiding the real cause. Create a temporary directory that is local, readable, and free of unrelated subtitle files.

1. Copy one short, known-good video into the directory.
2. Copy one valid SRT subtitle into the same directory.
3. Rename them Test.mkv and Test.srt.
4. Run mpv --no-config --sub-auto=exact "Test.mkv" from that directory.
5. Confirm that the external track appears.
6. Repeat without --no-config.
7. If the second test fails, reintroduce configuration sections, profiles, and scripts incrementally.

If both tests work, mpv itself is functioning. Return to the original media directory and compare filenames, permissions, search paths, and launch methods. Stop changing global settings as soon as the original subtitle is found reliably.

If the explicit --sub-file test works but neither automatic test works, capture a verbose log and verify the effective sub-auto behavior. If explicit loading also fails, replace the test subtitle with a small known-good UTF-8 SRT before concluding that mpv is broken.

6. Quick Fix Checklist

• Test the subtitle with --no-config --sub-file="subtitle.srt".
• Rename the files so their base names match exactly.
• Test --no-config --sub-auto=exact with Movie.mkv and Movie.srt.
• Try --sub-auto=fuzzy for language suffixes such as Movie.en.srt.
• Use --sub-auto=all only as a diagnostic or in controlled folders.
• Check mpv.conf for sub-auto=no or repeated subtitle options.
• Inspect active or suspected profiles with --show-profile.
• Verify sub-file-paths and test an absolute subtitle directory.
• Quote paths containing spaces and check for hidden double extensions.
• Confirm that the subtitle appears in the track list before troubleshooting display.
• Compare normal playback with a temporary --no-config run.
• Generate a verbose log before changing unrelated video, audio, HDR, or hardware settings.

7. Frequently Asked Questions

7.1 Why does Movie.srt load but Movie.en.srt does not?

The stricter matching mode may accept the identical base name while rejecting or overlooking the language-suffixed form in your particular setup. Test --sub-auto=fuzzy, retain the complete video base name at the start of the subtitle filename, and check whether a profile forces exact matching.

7.2 Should I permanently use sub-auto=all?

Usually not in directories containing multiple titles. It can make unrelated subtitle files available. Prefer exact matching for tightly controlled naming or fuzzy matching for normal language and release suffixes. Use all when the directory contains only the relevant media or when diagnosing matching behavior.

7.3 Why is the subtitle listed but not visible?

Auto-detection has already succeeded. Select the external track and check subtitle visibility, preferred subtitle languages, track ID settings, delay, and whether the subtitle contains cues for the current playback time. Do not continue changing discovery paths.

7.4 Can hardware decoding prevent subtitle discovery?

Hardware decoding does not normally control filesystem scanning or external subtitle discovery. It may affect rendering in some playback configurations, but a missing external track points first to matching, paths, permissions, options, profiles, or scripts.

7.5 Why does auto-detection work with no-config?

A user configuration option, profile, script, launcher argument, or custom binding is changing subtitle behavior. Search for subtitle-related settings, inspect profiles, and restore custom components one at a time. There is no need to delete your entire configuration folder.

7.6 Will same-folder detection work for online videos?

Not in the same way as a local file. A remote URL does not necessarily provide a local directory for mpv to scan. Supply a local subtitle with --sub-file. Investigate yt-dlp or network access only if the online media itself does not open.