mpv Subtitles Not Showing: How to Fix It

When mpv subtitles are not showing, the player is usually still reading the video correctly, but one part of the subtitle path has failed. Subtitles may be hidden, the wrong subtitle track may be selected, an external file may not have loaded, or a profile, script, input binding, or output setting may be overriding the expected behavior. Online videos and network streams introduce additional possibilities, including missing subtitle tracks, yt-dlp problems, and restricted network access.

The fastest approach is to establish whether subtitles work in a clean mpv session, then add your normal configuration back one layer at a time. Follow the steps below in order. After each change, look for the stated success condition. Once subtitles appear and remain visible, stop changing settings so you do not replace a simple fix with several new variables.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing configuration files, test the same media without your normal mpv configuration. The --no-config option prevents mpv from loading the standard user configuration, including options, profiles, scripts loaded through configuration, and custom input bindings.

Open a terminal or command prompt and run:

mpv --no-config "path/to/video.mkv"

On Windows, an example is:

mpv --no-config "C:\Videos\example.mkv"

On Linux or macOS, an example is:

mpv --no-config "/home/user/Videos/example.mkv"

Keep quotation marks around paths containing spaces, brackets, ampersands, or other characters interpreted by the shell. If you also have a known external subtitle file, load it explicitly:

mpv --no-config --sub-file="path/to/subtitles.srt" "path/to/video.mkv"

Success means the subtitle text appears over the video in this clean session. If that happens, the media, subtitle file, and basic subtitle renderer are working. The cause is probably in your normal mpv.conf, input.conf, profiles, scripts, or launch command. Stop investigating codecs, permissions, and GPU drivers for now, and proceed to the configuration checks.

If subtitles remain absent, press v once. The default v binding toggles subtitle visibility. Then press j to cycle through available subtitle tracks. The uppercase J binding cycles in the opposite direction under mpv's default input configuration. Do not press the keys repeatedly without observing the on-screen message, because you may cycle past the correct track.

Success means mpv reports a selected subtitle track and visible text appears when dialogue reaches a subtitled point. If no subtitle track is listed, the problem is track discovery or loading rather than subtitle visibility.

2. Check Subtitle Visibility, Selection, and Loading

2.1 Verify the Subtitle Track

A media file can contain several subtitle tracks, including forced signs, commentary, full dialogue, or tracks in different languages. It can also contain no subtitles at all. Press F9 with the default bindings to display the track list. If your build, terminal environment, or custom bindings do not respond to F9, inspect the terminal output generated when the file opens.

Look for subtitle entries and note which one is selected. You can also start mpv with a specific subtitle track ID after identifying it:

mpv --no-config --sid=2 "video.mkv"

The numeric ID is only an example. Use the ID displayed for your file. Setting an invalid ID will not produce the desired subtitle track.

Success means the track list marks the intended subtitle track as selected and its text appears during a known dialogue scene. At that point, save a preferred language or track-selection rule only if you need it for future files.

2.2 Distinguish Embedded and External Subtitles

Embedded subtitles are streams stored inside a container such as MKV or MP4. External subtitles are separate files, commonly using extensions such as SRT, ASS, SSA, VTT, or SUB. A video playing successfully does not prove that a separate subtitle file was found.

For an external subtitle, first test explicit loading with --sub-file. If that works, automatic matching is the problem. mpv's sub-auto option controls how aggressively it searches for external subtitle files. Automatic discovery also depends on filenames and search paths.

A reliable same-folder naming pattern is:

• Movie Name.mkv
• Movie Name.srt

Language suffixes can also be useful, such as Movie Name.en.srt, but an unusual or unrelated subtitle filename may not match as expected. To test broader discovery temporarily, run:

mpv --no-config --sub-auto=all "Movie Name.mkv"

Using sub-auto=all can load unrelated subtitle files from a crowded directory, so treat it as a diagnostic step rather than an automatic permanent fix. Explicit --sub-file loading is preferable when precise selection matters.

Success means the external subtitle appears without manually choosing it. If explicit loading works but automatic loading does not, adjust the filename, subtitle directory, or sub-auto policy. There is no reason to change video output or hardware decoding in that case.

2.3 Check Visibility and Styling Options

The subtitle track can be selected while rendering remains disabled. Check for options such as:

• sub-visibility=no
• sid=no
• sub-scale=0 or an impractically small scale
• Extreme subtitle position or margin settings
• Transparent subtitle colors or opacity settings
• no-sub or an equivalent command-line choice

Test explicit visibility without your configuration:

mpv --no-config --sub-visibility=yes --sub-file="subtitles.srt" "video.mkv"

For ASS subtitles, embedded styling may affect placement and appearance. If the track is technically visible but unreadable or positioned off-screen, test whether overriding problematic styling changes the result. Avoid making permanent style overrides until you have confirmed that styling is the actual cause.

Success means readable text appears in the video area. Once it does, stop adding visibility options and isolate the single style or position setting responsible.

3. Inspect Config Files, Profiles, Bindings, and Scripts

3.1 Review mpv.conf and Profiles

If --no-config fixes the problem, inspect your active configuration. Search mpv.conf and any included configuration files for sub, sid, alang, profile, and track-selection options. Also examine conditional profiles that activate for particular protocols, file extensions, display modes, HDR content, or high-resolution video.

A profile can disable subtitles even when the global configuration enables them. For example, a profile used for online URLs might contain sid=no, while a high-performance profile might invoke a script that changes tracks.

Use the --show-profile option to inspect a named profile:

mpv --show-profile=profile-name

This prints the profile's options rather than playing a file. Replace profile-name with the actual name from your configuration. Review profiles that activate automatically as well as those selected by launch scripts.

Do not delete the entire configuration folder. Instead, comment out one relevant line or temporarily rename one individual file, test again, and restore it if nothing changes. Success means you identify one option or profile that makes subtitles disappear when enabled.

3.2 Check input.conf and Runtime Commands

A custom input.conf can replace mpv's default bindings. In that situation, v, j, J, or F9 may perform a different action or nothing at all. Search for bindings that invoke commands such as cycle sub-visibility, change sid, or disable subtitles.

Also check keyboard automation, remote controls, front ends, and IPC clients. An IPC application can change subtitle visibility or the selected track after playback starts. If subtitles appear briefly and then vanish, a script or external controller is especially suspect.

Success means subtitles remain visible after temporarily disabling the specific binding, script, front end, or IPC command. Re-enable unrelated customizations once the responsible component is known.

3.3 Isolate User Scripts and Shaders

Scripts can select tracks, load external files, alter profiles, or respond to file-loaded events. Shaders normally process video rather than subtitle selection, but a complex rendering chain can still help expose an output-specific problem. Test without the normal configuration first, then add scripts individually.

If you manually pass scripts or shader options on the command line, remove them for the test. Do not assume every problem involving HDR or high-bitrate media is caused by hardware decoding. Track selection remains the more likely explanation when only subtitles are missing.

Success means the subtitle appears after one specific script or launch option is omitted. Update that component's configuration or remove only the conflicting behavior.

4. Check Files, Permissions, Streams, and Rendering

4.1 Verify File Access and Shell Quoting

mpv must be able to read an external subtitle file. Confirm that the file exists, is not empty, and is readable by the account running mpv. Sandboxed packages on Linux or macOS may have limited access to removable drives, network mounts, or directories outside their permitted scope.

Paths copied from a file manager may require quoting. In shells, characters such as spaces, parentheses, brackets, dollar signs, ampersands, and wildcard characters can alter the command. Explicitly quoted absolute paths eliminate much of this ambiguity.

Also confirm that the subtitle file contains recognizable timestamps and text. A file with the correct extension can still be malformed, encoded unusually, or contain timestamps outside the video's duration. Test the subtitle with another known-good short video only when timing is compatible, or test a known-good subtitle against the original video to separate file parsing from media-specific behavior.

Success means terminal output reports the external subtitle as loaded and the track list includes it. If the track exists but no text appears, move back to visibility, timing, and styling checks.

4.2 Diagnose Online URLs, yt-dlp, and Network Streams

For an online URL, subtitles must be exposed by the service, selected by mpv, and retrievable through the network path. Some streams contain subtitles in the media manifest, while others require yt-dlp to identify or obtain subtitle resources. A local file test can therefore succeed even when a URL has no accessible subtitle track.

Run the URL from a terminal and inspect whether any subtitle tracks are reported:

mpv --no-config "https://example.com/video-url"

If mpv relies on yt-dlp for that site, verify that your installed yt-dlp executable is found through the system path or the configuration you deliberately use. Install or update external tools only through their official project instructions or a trusted operating-system package source. Do not download random replacement binaries.

Network filtering, authentication, expired stream URLs, proxies, or unavailable subtitle segments can allow video playback while subtitle retrieval fails. Test the URL again, examine the log, and compare it with a local subtitle loaded explicitly alongside the stream:

mpv --no-config --sub-file="local-test.srt" "https://example.com/video-url"

If the local subtitle renders, mpv's subtitle display path works and the failure concerns the remote track or its retrieval. Audio backend changes will not fix a missing remote subtitle resource.

4.3 Test Video Output, Hardware Decoding, HDR, and GPU Drivers

Video output and hardware decoding are secondary suspects, but they become relevant when mpv reports a selected subtitle track while no overlay appears, particularly with unusual GPU drivers, display servers, HDR pipelines, or custom shader configurations.

Test without hardware decoding:

mpv --no-config --hwdec=no --sub-file="subtitles.srt" "video.mkv"

If needed, compare a supported video output configuration using options documented for your mpv build. Avoid copying obsolete output-driver commands from old forum posts. On Linux, note whether the failure occurs only under Wayland or X11. On Windows or macOS, compare behavior after installing supported operating-system and GPU-driver updates from the hardware vendor or OS update mechanism.

If disabling hardware decoding restores subtitles, collect a log before changing your permanent setup. The interaction may involve the selected decoder, output API, driver, HDR processing, or custom shaders. If subtitles remain absent in a clean software-decoded test, return to track loading and visibility instead of repeatedly changing GPU options.

4.4 Determine Whether Only Screenshots Lack Subtitles

Sometimes subtitles are visible during playback but missing from screenshots. That is a screenshot configuration issue, not an mpv subtitle playback failure. Check the screenshot-subtitles option and the exact screenshot command used by your input binding.

Test with subtitles enabled in screenshots:

mpv --no-config --screenshot-subtitles=yes "video.mkv"

Then take a screenshot while visible subtitle text is on screen. Success means the saved image contains the subtitle. If playback itself never displays text, screenshot settings are not the primary issue.

5. Use Logs and Runtime Diagnostics

5.1 Increase Terminal Detail With msg-level

mpv's terminal output can reveal whether a subtitle stream was discovered, selected, opened, or rejected. Increase relevant logging without turning every subsystem into maximum noise:

mpv --no-config --msg-level=all=v "video.mkv"

For a persistent record, use:

mpv --no-config --log-file=mpv-subtitle-test.log --msg-level=all=v "video.mkv"

Search the resulting log for terms such as sub, subtitle, sid, the subtitle filename, stream-selection messages, and errors. Logs may contain local paths, URLs, or environment details, so review and redact them before sharing publicly.

Success looks different depending on the failure. A loading fix produces a recognized subtitle stream. A selection fix shows the intended stream selected. A rendering fix produces visible text after the track was already known to mpv.

5.2 Use the Track List and Stats Overlay

The F9 track list is the clearest immediate check under default bindings. The stats overlay can also confirm playback state and rendering details, although it is not a replacement for the track list or log. Default key behavior can vary when custom input.conf entries override it, so use terminal diagnostics when a key produces unexpected results.

If no subtitle track appears anywhere, focus on the container, external file discovery, stream manifest, or yt-dlp. If a subtitle track appears and is selected, focus on visibility, timing, style, scripts, and rendering.

6. Run a Clean Temporary Test Before Permanent Changes

Use a controlled test matrix instead of changing many options at once:

1. Choose one known local video containing an embedded subtitle track, if available.
2. Choose one known-good external SRT file with matching timing.
3. Run mpv with --no-config.
4. Press F9 and confirm the subtitle track exists.
5. Press v once if visibility may be disabled.
6. Use j or J to select the intended track.
7. Load the external file explicitly with --sub-file.
8. Repeat with normal configuration but without optional scripts.
9. Re-enable profiles, scripts, shaders, front ends, and IPC automation one at a time.

This process separates media limitations from configuration errors. It also protects a carefully customized installation because you do not need to erase your settings. As soon as one re-enabled component causes subtitles to disappear, stop. You have identified the layer requiring correction.

7. Quick Fix Checklist

• Press v once to restore subtitle visibility.
• Press j or J and watch the selected subtitle track.
• Press F9 to confirm that a subtitle track exists.
• Run the file with mpv --no-config.
• Load an external subtitle explicitly with --sub-file.
• Match external video and subtitle filenames for automatic loading.
• Check sub-auto, sid, and sub-visibility settings.
• Inspect profiles with --show-profile.
• Review custom input.conf bindings and IPC commands.
• Temporarily remove individually loaded scripts and shaders.
• Quote file paths and verify subtitle-file permissions.
• For URLs, confirm the service actually exposes subtitles.
• Verify yt-dlp through official or trusted package sources.
• Test --hwdec=no only after confirming a subtitle track is selected.
• Create a log with --log-file before making deeper changes.

8. Frequently Asked Questions

8.1 Why Does Pressing v Fix Missing Subtitles?

With mpv's default bindings, v toggles subtitle visibility. The subtitle track can remain selected while its display is disabled, which makes the problem look like a loading failure. If v does nothing, test with --no-config because a custom input binding may have replaced the default action.

8.2 Why Does mpv Show No Subtitle Track for an MKV File?

An MKV container can hold subtitles, but it is not required to contain them. Use F9 or terminal output to inspect the actual streams. If no subtitle stream exists, load an external subtitle file. If another application lists a track that mpv does not, save a verbose mpv log and investigate parsing errors rather than assuming every MKV includes subtitles.

8.3 Why Are External Subtitles Not Loaded Automatically?

The subtitle may have an unrelated filename, be outside the searched directories, fail the current sub-auto policy, or be unreadable. Test it with --sub-file. If explicit loading works, rename it to match the video or configure an intentional subtitle search path.

8.4 Can Hardware Decoding Cause Subtitles to Disappear?

It is possible in an output or driver-specific failure, but it is not the first explanation to test. Confirm that the track exists and visibility is enabled, then compare playback with --hwdec=no. If only the hardware-decoded path fails, capture a log and inspect the GPU, video output, HDR, driver, and shader combination.

8.5 Why Do Subtitles Work With no-config but Not Normally?

This result proves that the core file and clean subtitle path work. The cause is likely an option, profile, input binding, script, front end, or IPC client in the normal setup. Reintroduce those layers individually. Do not delete the entire configuration folder, because a targeted comparison is safer and produces a clearer answer.

8.6 Why Are Subtitles Visible in Playback but Missing From Screenshots?

Playback overlays and screenshot output can be controlled separately. Check screenshot-subtitles and any custom screenshot binding. If --screenshot-subtitles=yes captures the visible text, subtitle playback is working and only the screenshot behavior needs adjustment.