mpv External Subtitles Not Loading: How to Fix It

When mpv external subtitles are not loading, the cause is usually narrower than it first appears. mpv may not have discovered the subtitle automatically, the subtitle track may be loaded but hidden, a configuration option or script may be overriding track selection, or the path may be interpreted from an unexpected working directory. Permissions, shell quoting, malformed subtitle files, remote media workflows, and frontend behavior can also contribute. The safest approach is to prove that mpv can load the video and subtitle in a clean session, then reintroduce your normal configuration one layer at a time.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start by bypassing your normal configuration and naming the subtitle file explicitly. This separates subtitle loading from automatic filename matching, profiles, scripts, shaders, hardware decoding, and custom input bindings.

1.1 Run a clean local-file test

On Linux or macOS, open a terminal and run a command like this:

mpv --no-config --sub-file="/full/path/movie.en.srt" "/full/path/movie.mkv"

On Windows PowerShell or Command Prompt, use the full paths to both files:

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

Replace the example paths with real files. Keep the quotation marks when a path contains spaces, parentheses, ampersands, or other shell-sensitive characters.

Success means the subtitle appears during a section of the video where the subtitle file contains a timed cue. You can also open mpv's track list or on-screen information and confirm that an external subtitle track exists. If this command works, stop investigating codecs, GPU drivers, HDR, and audio output. mpv can read the subtitle, so the problem is in automatic discovery, your normal invocation, or your configuration.

If the command fails, try a known-good UTF-8 SRT file with a simple local video. That helps distinguish a general loading problem from damage or unusual syntax in one ASS, SRT, or VTT file.

1.2 Pass both files deliberately

You can test by passing or dragging both files to mpv, but explicit assignment is more reliable than relying on file classification. The preferred terminal test remains:

mpv --sub-file="subtitle.ass" "video.mp4"

Some desktop environments, launchers, and mpv frontends handle multiple dragged files as playlist entries. If dragging the video and subtitle together creates a playlist instead of attaching the subtitle, that behavior does not prove subtitle support is broken. Use --sub-file, or start the video and drag the subtitle onto the active player window if your build and frontend support subtitle drop loading.

2. Check Subtitle Discovery and Track Selection

If explicit loading works, focus on how mpv discovers and selects external subtitles. Avoid changing video output, hardware decoding, or shader settings unless the track is present but not rendered.

2.1 Match the subtitle filename to the video filename

Place the video and subtitle in the same directory and give them the same base filename. Language or descriptive suffixes are commonly used after the shared base name.

• Example Movie.mkv and Example Movie.srt
• Example Movie.mkv and Example Movie.en.srt
• Example Movie.mkv and Example Movie.forced.ass

A subtitle named subs-final-2.srt may not be selected automatically for Example Movie.mkv, even when both files are in the same folder. Rename it temporarily to Example Movie.srt and reopen the video.

Success means mpv discovers the subtitle without --sub-file. Once that happens, stop changing settings. The failure was filename discovery, not subtitle rendering.

2.2 Review automatic subtitle options

Options related to external subtitle discovery include sub-auto and sub-file-paths. The exact accepted values and path-list syntax should be checked against the manual for your installed mpv build.

For a direct diagnostic test, force broad automatic matching for one launch:

mpv --no-config --sub-auto=all "/full/path/movie.mkv"

If this finds the subtitle while your normal launch does not, inspect mpv.conf, command aliases, launcher arguments, and profiles for a restrictive sub-auto value. Also check whether subtitles are stored in a separate folder and whether sub-file-paths points to that folder correctly.

Do not leave broad matching enabled merely to hide inconsistent naming. It can select unrelated subtitle files when a directory contains many videos. Matching base names is generally more predictable.

2.3 Confirm the subtitle is visible and selected

A loaded track can still appear missing if subtitle visibility is disabled or no subtitle track is selected. Check these areas:

• Toggle subtitle visibility using your current input binding
• Cycle through subtitle tracks and look for the external SRT, ASS, or VTT track
• Check whether sid has been set to no or to another track ID
• Check whether subtitle position, scale, or margins place text outside the expected area
• Look for ASS style overrides that make text transparent, tiny, or off-screen

For a temporary launch, you can request automatic subtitle-track selection with --sid=auto and ensure visibility is enabled with --sub-visibility=yes.

Success means the external track is listed, selected, and visible. If the track appears in the list but produces no text, test a timestamp known to contain dialogue before assuming rendering is broken.

3. Inspect Configuration, Profiles, Bindings, and Scripts

A customized mpv installation can alter subtitle behavior in several places. Because --no-config disables normal configuration loading, a clean command that succeeds is strong evidence that one of these custom layers is responsible.

3.1 Compare the clean test with your normal launch

Run the same video and subtitle twice:

1. Use mpv --no-config --sub-file="subtitle.srt" "video.mkv"
2. Remove --no-config but keep the same explicit paths

If only the second command fails, inspect your configuration incrementally. Do not delete the entire config directory. Temporarily rename one relevant file or disable one option at a time so that the cause remains identifiable.

Search mpv.conf and profile sections for subtitle options such as sid, sub-auto, sub-file-paths, sub-visibility, slang, subtitle delay, subtitle scaling, and ASS override behavior. A profile activated for a protocol, extension, display mode, or high-resolution video may produce different behavior from your default profile.

3.2 Check input bindings

Custom entries in input.conf can replace default keys. A key you expect to cycle subtitles might now run a script command, change audio tracks, or do nothing. Use mpv's interactive console if enabled, or inspect input.conf directly.

If a binding invokes sub-visibility, cycle sid, or a script-defined subtitle command, test without that binding. Success means the subtitle becomes visible or selectable using a direct property command or a clean default session.

3.3 Disable scripts selectively

Subtitle downloaders, track-selection scripts, playlist managers, autoload scripts, and custom user interfaces can modify track state after a file opens. Temporarily move only the suspected script out of the scripts directory, or use a separate temporary config directory if supported by your workflow.

Do not begin by removing shaders, HDR settings, IPC clients, yt-dlp, and every script simultaneously. If explicit subtitle loading works with the normal config but fails only after a specific script initializes, you have found the relevant layer.

3.4 Understand unrelated settings

Hardware decoding, HDR tone mapping, GPU output, audio backends, screenshots, and yt-dlp usually do not control whether a local external subtitle file is discovered. They matter only in specific circumstances:

• A video output or GPU problem may matter if the subtitle track is loaded but no overlay is rendered
• A severe playback failure may prevent the video from reaching subtitle timestamps
• yt-dlp matters when mpv is resolving an online page rather than opening a direct media URL
• Screenshot settings matter only when subtitles appear during playback but are absent from screenshots
• Audio-track settings do not normally prevent an external subtitle track from loading

Keep these systems out of the first troubleshooting pass. This prevents an external-subtitle problem from turning into an unrelated mpv player issue.

4. Check Paths, Permissions, and Operating System Behavior

4.1 Use absolute paths to eliminate working-directory errors

A relative subtitle path is resolved from mpv's working directory, which may not be the video's directory. This commonly happens with shortcuts, shell scripts, desktop launchers, file managers, IPC clients, and third-party frontends.

For example, this command depends on the current directory:

mpv --sub-file="subs/movie.srt" "/media/videos/movie.mkv"

Replace the relative subtitle location with an absolute path. If that works, correct the launcher's working directory or generate absolute paths in your script. Success means the subtitle track appears as soon as the absolute path is used.

4.2 Quote paths with spaces correctly

Pass each complete path as one quoted argument. Do not put both the option and video path inside one large pair of quotes.

Correct:

mpv --sub-file="C:\Media Files\Subs\Movie English.srt" "C:\Media Files\Movie.mkv"

On POSIX shells, single quotes are useful when filenames contain characters the shell would otherwise expand:

mpv --sub-file='/home/user/Media/Movie [English].srt' '/home/user/Media/Movie.mkv'

Shell syntax differs between Bash, Zsh, fish, PowerShell, and Command Prompt. If a copied command fails, verify quoting in the shell you are actually using.

4.3 Verify read permissions and sandbox access

The user running mpv must be able to read the subtitle and traverse its parent directories. On Linux and macOS, check file ownership and permissions. On macOS, an app or frontend may also need permission to access protected folders. Sandboxed packages on Linux may not be able to read arbitrary mounted drives or directories until access is granted.

On Windows, check whether the subtitle is in a protected, network, cloud-synced, or unavailable location. Copy the video and subtitle to a simple local test directory you can read, then retry the clean command. Do not weaken system-wide permissions as a first response.

4.4 Check the subtitle file itself

An external file can exist and still contain invalid or unsupported content. Confirm that its extension matches its actual format and that it contains timed subtitle entries rather than HTML, an error page, or a download portal response.

• SRT files normally contain numbered cues, timestamps, and text
• ASS files normally contain script sections and dialogue events
• WebVTT files normally begin with a WebVTT declaration and contain timed cues

Open the file in a text editor. If the text is unreadable, test a UTF-8 copy without overwriting the original. If another known-good subtitle loads through the same command, mpv itself is working and the original subtitle needs repair or conversion with a trusted tool.

5. Handle Remote Videos and Local Subtitles Carefully

A remote video and a local subtitle can often be used together when the local file is supplied explicitly in the same mpv invocation:

mpv --sub-file="/home/user/subs/program.srt" "https://example.com/video.mp4"

However, frontends and scripts may launch the remote URL separately, discard local options, or move between playlist entries. A relative subtitle path still refers to the local working directory, not the remote URL's directory.

For a page URL handled through yt-dlp, first verify that mpv can open the page without the subtitle. Then add the absolute local --sub-file path. If the page does not resolve at all, fix the yt-dlp or network problem first because mpv has no playable timeline to which it can attach the subtitle.

Streams can also change programs, timelines, or playlist items. A subtitle timed for one recording may be loaded correctly but never align with a live or discontinuous stream. Check the track list to distinguish loading from synchronization.

6. Use Logs and Runtime Information to Find the Exact Failure

6.1 Increase subtitle-related terminal output

Launch mpv from a terminal so that errors remain visible. A broad diagnostic command is:

mpv --no-config --msg-level=all=v --log-file="mpv-subtitle-test.log" --sub-file="/full/path/subtitle.srt" "/full/path/video.mkv"

Search the log for the subtitle filename, path errors, permission failures, parsing messages, and track-selection events. Avoid publishing the complete log without reviewing it because it can contain local paths, URLs, tokens, or other private information.

6.2 Inspect the track list and stats

Use mpv's track list or on-screen information to answer a precise question: did mpv load the external subtitle track? If the track is absent, investigate paths, permissions, discovery, and parsing. If the track is present but not selected, investigate sid, language preferences, visibility, and scripts. If it is selected but invisible, investigate timing, styling, subtitle position, and video output.

The stats overlay is useful for confirming playback state and diagnosing video-output problems, but it does not replace the track list. Likewise, IPC users can query mpv's track-list property to see whether an external subtitle was registered.

6.3 Examine profiles without guessing

If a named profile may be involved, use --show-profile with the profile name to inspect what it contains. Compare those options with the command that worked under --no-config. Profiles associated with protocols, file types, HDR content, or high-bitrate playback deserve attention only if they also modify subtitle or track-selection properties.

7. Run a Clean Temporary Test Before Making Permanent Changes

Use one local video, one known-good subtitle, simple filenames, and a directory you can read. A reliable sequence is:

1. Rename the files to test.mkv and test.srt
2. Place both files in the same local directory
3. Run mpv with --no-config and an absolute --sub-file path
4. Confirm the external subtitle track appears
5. Remove --sub-file and test automatic discovery
6. Enable your normal configuration
7. Reintroduce profiles, scripts, frontend arguments, and IPC automation one at a time

Stop as soon as the first transition causes failure. The last change identifies the area to fix. This method is faster and safer than replacing mpv, installing codec packs, changing GPU drivers, or deleting a complete configuration directory.

8. Quick Fix Checklist

• Match the subtitle base filename to the video filename
• Keep the video and subtitle in the same directory for the first test
• Use --sub-file with an absolute path
• Quote every path containing spaces or shell-sensitive characters
• Run once with --no-config
• Confirm the external track appears in the track list
• Enable subtitle visibility and select the correct subtitle track
• Check sub-auto, sub-file-paths, sid, and profiles
• Disable only suspected subtitle or track-selection scripts
• Verify permissions and sandbox access
• Open the subtitle in a text editor and verify its real format
• Use --msg-level and --log-file when the cause remains unclear

9. Frequently Asked Questions

9.1 Why does mpv load a subtitle with --sub-file but not automatically?

The most likely cause is filename discovery. Give the subtitle the same base name as the video, place it beside the video, and review sub-auto and sub-file-paths. A working --sub-file test proves that mpv can read and render the file.

9.2 Can mpv use a local subtitle with an online video?

Often, yes. Supply the local subtitle using an absolute --sub-file path in the same command as the URL. The online media must resolve and play, and a frontend or playlist script must not discard the local subtitle option when it changes entries.

9.3 Why does the subtitle track appear but show no text?

Check that you are at a timestamp containing a cue. Then verify subtitle visibility, selected track ID, subtitle delay, position, scale, and ASS styling. A subtitle created for a different video cut may also have timing that is far out of sync.

9.4 Do I need a codec pack for SRT, ASS, or VTT subtitles?

No general-purpose codec pack should be the first fix. mpv includes subtitle handling through its normal playback components. A known-good subtitle that loads under --no-config confirms that extra codec installations are unnecessary for this symptom.

9.5 Can hardware decoding or HDR stop external subtitles from loading?

They do not normally control subtitle discovery. They may become relevant when the track is loaded and selected but overlays are not rendered correctly, or when video output fails entirely. Check the track list before changing hwdec, GPU output, shaders, or HDR options.

9.6 When should I stop troubleshooting?

Stop changing settings when the subtitle is listed, selected, and visible during a known subtitle cue. If explicit loading works but automatic loading does not, limit further work to naming and discovery settings. If only the configured session fails, focus on the exact profile, option, binding, script, or launcher argument that differs from the clean test.