mpv Fontconfig Subtitle Font Missing: How to Fix It

When mpv reports that a subtitle font is missing, displays boxes instead of characters, or substitutes an unexpected typeface, the underlying problem is usually font lookup rather than video decoding. Common causes include an incorrect font family name, an unavailable system font, a disabled or broken fontconfig setup on Linux, an unreadable embedded font attachment, or an mpv option that overrides the subtitle style. The safest approach is to reproduce the problem with a clean command, identify whether the requested font is installed or attached, and change one relevant setting at a time.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start by determining whether the problem comes from the media, the subtitle file, or your normal mpv configuration. Do not delete your configuration folder. Instead, temporarily bypass it with --no-config.

Open a terminal, PowerShell window, or Command Prompt and run mpv against a local file:

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

On Windows, use the full executable path if mpv is not available through PATH:

"C:\path\to\mpv.exe" --no-config "C:\Media\video.mkv"

Use quotes whenever a path contains spaces, brackets, ampersands, or other characters interpreted by the shell. PowerShell users may need its call operator when invoking a quoted executable path:

& "C:\path\to\mpv.exe" --no-config "C:\Media\video.mkv"

1.1 Interpret the clean test

If the correct font appears under --no-config, the font is discoverable and the problem is probably an option, profile, script, or style override in your regular setup. If the font remains wrong, investigate the requested family, installed fonts, and embedded attachments.

Success means the subtitle text uses the intended typeface and all expected characters render correctly. Once that happens, stop changing unrelated playback options. Hardware decoding, HDR tone mapping, audio output, and video output generally do not control subtitle font discovery.

1.2 Compare text and styled subtitles

Subtitle formats behave differently. Plain SRT subtitles normally have no embedded font styling, so mpv uses its configured or default subtitle font. ASS and SSA subtitles can request specific font families and styles. Matroska files can also contain font files as attachments for use by styled subtitles.

If an SRT file displays correctly but an ASS track does not, inspect the ASS style and embedded attachments first. If every text subtitle uses the same unwanted font, check sub-font and your system font installation.

2. Check the Font Options and Subtitle Settings Directly

The mpv option most directly related to this symptom is --sub-font. It specifies the font used for text subtitles when the subtitle renderer is allowed to select that font. Test it without editing your permanent configuration:

mpv --no-config --sub-font="DejaVu Sans" "video.mkv"

Replace DejaVu Sans with the actual family name installed on your system. A filename such as MyFont-Bold.ttf is not necessarily the family name. Font files contain internal family and style metadata, and applications normally search using that metadata.

2.1 Verify the family name instead of guessing

On Linux, use fontconfig to list or match fonts:

fc-match "DejaVu Sans"
fc-list : family | sort -u

If fc-match returns a different family, the requested font is unavailable or an alias is resolving to a substitute. If it returns the intended font file, fontconfig can discover it.

On Windows, open Settings and navigate to the installed-fonts page, or use the Fonts control panel. Select the font and confirm its displayed family name. Merely copying a font file beside a video does not install it or make it an attachment. Install it through Windows when licensing and permissions allow, then restart mpv.

On macOS, open Font Book, search for the font, and verify that it is enabled. Resolve any disabled or duplicate font warnings shown by Font Book, then fully quit and reopen mpv.

2.2 Inspect mpv.conf for overrides

Search your active mpv.conf for subtitle-related settings, especially:

• sub-font=...
• sub-font-size=...
• sub-ass-override=...
• sub-ass-style-overrides=...
• sub-file=...
• sid=... or subtitle track-selection settings

A line beginning with # is a comment. Check for duplicate options because a later value can replace an earlier one. Also inspect profile blocks such as [anime], [protocol.http], or conditional profiles that may activate only for certain files.

For an ASS subtitle that intentionally requests its own fonts, aggressive style overrides can make the result appear unrelated to the authored style. Test the file under --no-config before changing those overrides permanently.

2.3 Check input bindings, profiles, and scripts

An input.conf binding can change properties during playback. Search it for commands involving sub-font, sub-ass-override, subtitle visibility, track selection, or profile application. Also inspect user scripts that alter subtitle properties.

Run the following to see whether a named profile exists and what it contains:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the profile you suspect. If playback is correct with --no-config but wrong normally, re-enable configuration components incrementally. Begin with mpv.conf, then input bindings, then scripts. Stop as soon as the offending component is identified.

3. Check System Font Discovery and Embedded Attachments

3.1 Confirm fontconfig availability on Linux

Linux builds of mpv commonly rely on fontconfig-backed discovery for subtitle fonts. Confirm that the command-line utilities are available:

fc-match sans-serif
fc-cache --version

If the shell reports that these commands are missing, install fontconfig through your distribution's official package manager. Package names and commands differ by distribution, so use the distribution's documented repository rather than downloading random binaries.

After installing a font for your account, confirm that its directory is covered by fontconfig. Typical per-user locations include ~/.local/share/fonts and, on some systems, ~/.fonts. Then rebuild the cache:

fc-cache -f -v

Restart mpv after the rebuild because an already running process may retain previously loaded font information. Success means fc-match "Requested Family" resolves to the expected file and a newly started mpv process renders it.

3.2 Verify Windows font discovery

On Windows, install the font for the current user or for all users through the normal Windows interface. A font installed only for another account may not be visible to the account running mpv. If mpv is running under a different user, service context, sandbox, or elevated account, compare that context with the account that installed the font.

Close every mpv window and start a new process after installation. If the family still cannot be selected, verify that the font supports the text's writing system. A Latin-only font cannot render Japanese, Arabic, Devanagari, or many symbols. In that case, fallback is expected for unsupported characters even when the primary family is found.

3.3 Inspect embedded font attachments

ASS subtitles often depend on fonts attached to an MKV file. Use mpv's track information or a trusted Matroska inspection tool to confirm that attachments exist. In mpv, press i during playback to open the stats overlay, then inspect the available track and file information. Terminal output may also identify attachments and subtitle tracks.

Test attachment behavior explicitly:

mpv --no-config --embeddedfonts=yes "video.mkv"

The embeddedfonts option controls whether attached fonts are used by the subtitle renderer. If your configuration sets it to no, an ASS track may fall back to system fonts even though the MKV includes the requested typeface.

If the MKV has no font attachments, mpv cannot invent the missing typeface. Install a legally obtained copy of the font, choose an available replacement, or edit your own subtitle style to request an installed family. Do not download fonts from untrusted archives.

3.4 Separate font lookup from media limitations

A damaged ASS file may request a misspelled family or contain malformed style information. Open a copy in a text editor and inspect the [V4+ Styles] section. The font name in a style line should match an internal family name, not merely a font filename.

External SRT files placed near a video do not bring fonts with them. Likewise, a network stream may carry subtitles without supplying the fonts expected by those subtitles. If the same subtitle file produces the same fallback with a local test video, the stream, network, yt-dlp path, and decoder are not the root cause.

4. Use mpv Logs to Identify the Lookup Failure

Verbose terminal output is more useful than repeatedly changing options. Run a clean test with focused subtitle and font messages:

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

Because verbose output can be extensive, write it to a file:

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

Search the log for terms such as font, fontconfig, libass, attachment, fallback, and the requested family name. The exact wording depends on the build and platform, so focus on the sequence: requested family, selected font, and any failed attachment or file access.

4.1 Confirm the active subtitle track

A font investigation can be misleading if mpv is rendering a different subtitle track than expected. Press i for stats and use mpv's track controls to verify the selected subtitle. You can also review terminal output at startup for the track list.

For a controlled test, select the intended subtitle track explicitly with --sid=ID, replacing ID with its track number:

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

If the correct track renders properly, stop troubleshooting font discovery. The original problem was track selection rather than a missing font.

4.2 Know which settings are unlikely to matter

Video output drivers, GPU APIs, hardware decoding, HDR profiles, audio backends, screenshot templates, playlists, IPC, and yt-dlp paths can cause other mpv problems, but they normally do not determine which font libass selects. Change them only if the log shows a related failure or if subtitles are not being rendered at all.

For example, if subtitle text appears but uses the wrong family, the video decoder is already delivering frames and the subtitle renderer is already active. Concentrate on font names, attachments, font discovery, and subtitle overrides.

5. Run a Clean Temporary Test Before Permanent Changes

Create a small test matrix rather than changing several options simultaneously. Use one local video with a known subtitle track and run these tests in order:

1. Run mpv --no-config "video.mkv".
2. Run with an installed family using --sub-font="Known Family".
3. For an MKV with ASS subtitles, add --embeddedfonts=yes.
4. Confirm the selected subtitle track with the stats overlay and track list.
5. Capture a verbose log only if the lookup remains unclear.

If the second test works, the font discovery mechanism is functional and the requested family or permanent setting is wrong. If only the third test works, embedded fonts were disabled or overridden. If none work but fc-match also fails on Linux, repair the fontconfig installation or cache before touching mpv profiles.

After identifying the smallest successful command, transfer only the necessary setting to mpv.conf. For example:

sub-font=DejaVu Sans
embeddedfonts=yes

Restart mpv and test the same file. Success means the permanent configuration behaves like the successful temporary command. At that point, do not continue modifying scripts, GPU settings, or unrelated playback profiles.

6. Quick Fix Checklist

• Reproduce the issue with mpv --no-config.
• Confirm that the intended subtitle track is selected.
• Use the font's internal family name with --sub-font.
• On Linux, verify the family with fc-match.
• Install missing Linux fonts through trusted distribution repositories or legitimate font sources.
• Rebuild the Linux font cache with fc-cache -f -v.
• On Windows, verify installation in Settings or the Fonts control panel.
• On macOS, confirm that Font Book shows the font as enabled.
• Restart mpv after installing fonts or rebuilding caches.
• For ASS subtitles in MKV files, test --embeddedfonts=yes.
• Search mpv.conf, profiles, input.conf, and scripts for overrides.
• Use a verbose log to see the requested and selected families.
• Stop once the clean test and permanent setup render the same correct font.

7. Frequently Asked Questions

7.1 Why does mpv use a different font than the one I selected?

The requested family may not be installed, its internal name may differ from its filename, or it may lack glyphs for some characters. mpv's subtitle renderer then uses a fallback font. ASS style rules and configuration overrides can also request a different family.

7.2 Does mpv require fontconfig on Windows?

Windows font discovery differs from a typical Linux fontconfig setup. Use Windows' normal font installation interface, verify the family name, and restart mpv. Do not assume Linux cache commands apply to a native Windows installation.

7.3 Why are embedded MKV fonts ignored?

The file may not actually contain attachments, embeddedfonts may be disabled, the attachment may be unreadable, or the subtitle style may request a different family name. Test with --no-config --embeddedfonts=yes and inspect the verbose log.

7.4 Can I point sub-font directly to a TTF filename?

sub-font is intended to identify a font family, not act as a general font-file path. Install the font properly or make it a valid Matroska attachment, then refer to its internal family name.

7.5 Why do only some subtitle characters use the wrong font?

The primary font probably lacks those glyphs. Font fallback operates at the character level, so unsupported scripts, symbols, or emoji may come from another font. Select a family with suitable language coverage or accept an appropriate fallback.

7.6 Should I reinstall mpv or delete its configuration?

Not initially. A --no-config test provides the same isolation without destroying settings. Reinstallation is unlikely to fix a misspelled family, missing system font, disabled embedded fonts, or stale font cache. Preserve your configuration and narrow the cause first.