mpv Install Build Missing libass: How to Fix It

If mpv reports that your install or build is missing libass, subtitles may disappear, lose styling, use incorrect fonts, or render differently from what the subtitle author intended. This is primarily a subtitle-renderer problem, not a general codec, HDR, audio, hardware-decoding, or yt-dlp failure. The usual causes are an mpv package built without libass support, a minimal or outdated binary, disabled subtitle rendering, a conflicting configuration option, or missing fonts required by an ASS subtitle track.

The safest approach is to confirm the symptom with a clean command, distinguish a missing renderer from a font problem, and inspect mpv's own terminal output before reinstalling anything. Change one variable at a time. Once a clean test renders both basic SRT and styled ASS subtitles correctly, stop changing unrelated video, audio, HDR, or network options.

1. Confirm the Symptom With a Minimal Clean mpv Command

Start by removing your normal configuration, scripts, shaders, profiles, and input bindings from the test without deleting them. The temporary --no-config option tells mpv not to load its regular configuration files for that invocation.

Open Command Prompt, PowerShell, Terminal, or your preferred shell and run:

mpv --no-config --sub-auto=no --sid=no video-file.mkv

This first command establishes that the video opens without selecting a subtitle track. Then test a known external subtitle explicitly:

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

Replace the filenames with real paths. Quotes are important when a path contains spaces, brackets, or shell-sensitive characters. In PowerShell and Unix-like shells, placing the complete path inside quotes is usually the least ambiguous approach.

Success means the video opens and the SRT text appears at the expected times. If the video does not open at all, first correct the file path or media-access problem. A failure to open the video is not evidence that libass is missing.

1.1 Compare Simple SRT and Complex ASS Subtitles

A useful diagnostic comparison requires two known-good subtitle files:

• A simple SRT file containing ordinary timed text
• An ASS file containing visible styling, positioning, fonts, or effects

Run each file explicitly:

mpv --no-config --sub-file="simple.srt" video-file.mkv
mpv --no-config --sub-file="styled.ass" video-file.mkv

If neither subtitle appears, investigate track selection, subtitle visibility, or a genuinely incomplete build. If SRT appears but ASS does not, or ASS appears without its expected styling, libass support and font availability become the leading suspects.

Do not assume that readable SRT output proves full ASS support. SRT mainly carries timing and text, while ASS can specify font families, colors, outlines, margins, positioning, animation, and other presentation details. A build intended for normal desktop use should include proper ASS rendering support.

1.2 Verify Subtitle Visibility and Track Selection

Force subtitle visibility and select a subtitle track:

mpv --no-config --sub-visibility=yes --sid=1 video-file.mkv

The number accepted by --sid depends on the available tracks. Press i during playback to open mpv's statistics and track information, or inspect the terminal output when the file loads. You can also cycle subtitle tracks with the default subtitle-cycle binding if your build and input configuration retain that binding.

Success means mpv identifies a subtitle track and displays it. If the track is selected but the log reports unavailable ASS rendering support, move to package and build checks rather than adjusting video output.

2. Check Subtitle Options, Configuration, Profiles, and Scripts

A full-featured build can look broken when a configuration option disables subtitles or selects the wrong track. Test the relevant settings directly before changing GPU, audio, HDR, or hardware-decoding options.

2.1 Inspect mpv.conf for Subtitle Overrides

Open your mpv.conf file in a text editor and search for subtitle-related entries. Depending on the configuration, relevant options may include:

• sub-visibility=no, which hides subtitles
• sid=no, which prevents subtitle selection
• sub-auto=no, which prevents automatic loading of external subtitle files
• sub-file, which forces a particular external subtitle file
• slang, which influences language-based track selection
• sub-font, which requests a particular font
• sub-ass=no, which can disable ASS styling while retaining subtitle text
• sub-ass-override, which can alter or replace aspects of ASS styling

Temporarily comment out only suspicious lines, or override them on the command line. For example:

mpv --sub-visibility=yes --sid=auto --sub-ass=yes video-file.mkv

Command-line options normally let you test a correction without permanently editing the file. Success means subtitles work with the override. At that point, correct the matching configuration line and stop. There is no reason to reset unrelated HDR, audio, shader, or hardware-decoding settings.

2.2 Check Profiles and Input Bindings

A profile can reintroduce an option that is absent from the main section of mpv.conf. Look for profile blocks that apply by file type, protocol, resolution, or another condition. Use this command to display a named profile:

mpv --show-profile=profile-name

Replace profile-name with the profile you want to inspect. Compare its options with the clean test.

Also inspect input.conf for bindings that toggle sub-visibility, change sid, or modify subtitle styling. A custom key may have left subtitles hidden without making the cause obvious. If subtitles reappear after explicitly setting sub-visibility=yes, the renderer itself may be working correctly.

2.3 Isolate Scripts Without Deleting Them

Scripts can change tracks, react to file-loaded events, or apply profiles. Use --no-config for the first clean test because it also avoids the normal configuration environment. If you need a narrower comparison, temporarily prevent script loading for one invocation:

mpv --no-scripts --sub-file="styled.ass" video-file.mkv

If ASS subtitles work without scripts, re-enable scripts one at a time or review recently changed script settings. Success means you identify the single script or option responsible. Do not delete your entire configuration directory as a first response.

2.4 Avoid Unrelated Track and Output Changes

Audio track selection, video track selection, vo, ao, hwdec, HDR tone mapping, shaders, screenshots, IPC, yt-dlp, and network-stream settings generally do not add libass to a build. They can affect whether playback starts, but they cannot repair a compiled-out subtitle dependency.

If the same local video plays normally and only subtitle styling is absent, leave those settings unchanged. If playback itself fails, test the local file separately before combining that issue with subtitle troubleshooting.

3. Verify libass Support, Package Build Options, and Fonts

libass is the subtitle-rendering library used for SSA and ASS subtitles. An mpv executable must be built with the appropriate support for it. Installing a library package after the fact may not repair an mpv binary that was compiled without that feature.

3.1 Read the Version and Build Information

Run:

mpv --version

Review the output for the mpv build identity, linked library information, and build configuration details provided by that package. The exact output varies by operating system, packaging method, and build system, so do not rely on one universal line appearing in every release.

Next, start the ASS test from a terminal and watch messages related to subtitles, ASS, fonts, and filters. A direct error indicating that the build lacks required subtitle-renderer support is stronger evidence than subtitles merely looking wrong.

Success at this stage means either the output confirms a package limitation or shows that libass initializes and the remaining problem concerns track selection or fonts. Stop treating the issue as a missing dependency if the renderer initializes and styled ASS content displays correctly.

3.2 Understand Package Build Options

Linux distributions and third-party package maintainers decide which optional dependencies are enabled when they compile mpv. Minimal, embedded, headless, or custom packages may omit functionality available in a normal desktop package. Similarly, a locally compiled mpv only gains libass support when the required development files are available and the build configuration detects them.

If you compiled mpv yourself, inspect the configuration summary generated during the build. Install the libass development package provided by your operating system, reconfigure from a clean build directory when appropriate, and verify that subtitle support is detected before compiling again. Package names vary by distribution, so use the official package manager and distribution documentation rather than copying an unverified package name.

If you did not compile mpv yourself, installing the standard full-featured mpv package is usually safer than attempting to patch an unknown binary. Avoid random download sites and bundled codec packs. mpv includes its playback stack through legitimate libraries and does not need an untrusted codec bundle to render ASS subtitles.

3.3 Recognize Font Fallback Symptoms

A font problem is different from missing libass. Common font fallback symptoms include:

• Subtitles appear, but the typeface is visibly wrong
• Text spacing or line wrapping differs from the intended layout
• Some characters become empty squares or replacement symbols
• Signs overlap because the substitute font has different metrics
• Latin text works, but another writing system is missing glyphs

These symptoms show that subtitle rendering is occurring. Check whether the required fonts are embedded as attachments in the media file or installed on the operating system. mpv and libass can use attached fonts when the build and file expose them correctly. For external ASS files, you may need to install legitimately obtained fonts or place approved font files in a directory supplied through mpv's font-related options.

After adding fonts, restart mpv so font discovery can run again. Success means the expected typeface and glyphs appear. Once they do, do not reinstall mpv or alter video decoding.

3.4 Install a Full-Featured Build Safely

On Linux, prefer the distribution's official package manager or another repository you already trust. Check whether you accidentally installed a minimal variant, a custom headless package, or an old locally built executable that appears earlier in your shell's PATH.

On macOS, determine which mpv executable your shell launches and whether it came from your chosen trusted package manager. An older manual copy can shadow a newer package-managed installation.

On Windows, identify the exact executable used by your shortcut, terminal, or file association. Multiple copies of mpv.exe can produce confusingly different behavior. Use a reputable build source referenced by the mpv project rather than a generic binary-download website.

After replacement, run mpv --version again from the same shell, then repeat the clean ASS test. Success means the terminal invokes the intended executable and the styled subtitle renders correctly.

4. Check Paths, Permissions, Media Attachments, and Operating System Limits

When the renderer exists but subtitles remain absent, verify that mpv can actually read the subtitle file and any external font directory. A permissions or path failure can resemble a renderer problem.

4.1 Validate File Paths and Shell Quoting

Use absolute paths for one diagnostic run:

mpv --no-config --sub-file="/full/path/to/styled.ass" "/full/path/to/video.mkv"

On Windows, use quoted absolute Windows paths. If the subtitle filename begins with a hyphen, use a fully qualified path so it is not mistaken for an option. Confirm that the current user can read both files.

Success means the explicitly supplied subtitle loads. If it works only with the absolute path, correct your working directory, automatic subtitle naming, or quoting rather than reinstalling libass.

4.2 Inspect Embedded Subtitle and Font Attachments

A Matroska file may contain subtitle tracks and font attachments. Open the stats overlay or review startup output to confirm that the expected subtitle track exists. If another player shows styled subtitles but mpv lists no subtitle track, the file, selected edition, or demuxing path deserves investigation.

Test an external known-good ASS file against the same video. If external ASS works, libass is available and the original media may have a damaged track, unusual attachment metadata, or no subtitle track at all. Stop modifying global settings and inspect that file specifically.

4.3 Separate Local Playback From Streams and yt-dlp

For an online URL, playlist, or network stream, first reproduce the subtitle test with a local video and local ASS file. yt-dlp can help mpv resolve supported website URLs, but it does not supply libass. Network permissions, expiring URLs, authentication, or unavailable subtitle formats can prevent remote subtitles from reaching mpv even when local ASS rendering is perfect.

If local ASS works, your build has functioning subtitle-renderer support. Investigate the remote source, available tracks, yt-dlp installation path, and network access separately. Do not replace a working mpv build merely because one website does not provide a subtitle track.

5. Use Logs and Track Information to Find the Exact Failure

Terminal output is more useful than repeatedly changing options. mpv can increase message detail and save a log for careful inspection.

5.1 Create a Focused Diagnostic Log

Run a clean test with a log file:

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

Search the resulting text file for terms such as ass, sub, font, attachment, error, and failed. Verbose logs can contain local file paths and media metadata, so review and redact them before posting publicly.

Look for a concrete sequence: mpv opens the subtitle file, identifies its format, initializes the renderer, resolves fonts, and draws subtitle events. The first failed step usually identifies the correct category of fix.

5.2 Use the Stats Overlay and Track List

During playback, press i to inspect the stats overlay. The available pages and details can vary with mpv's bundled scripts and configuration, but the overlay can help confirm selected audio, video, and subtitle tracks.

The key questions are:

• Does mpv list the expected subtitle track?
• Is that track selected?
• Does the subtitle timeline contain events at the current playback position?
• Does the terminal report font or renderer failures?

If the track exists and is selected but has no events at the current timestamp, seek to a known subtitle line. A subtitle that begins several minutes into a video can make a healthy renderer appear broken.

5.3 Compare Configured and Clean Runs

Create two logs, one from your normal invocation and one using --no-config. If only the configured run fails, the installed build probably supports libass. Compare subtitle options, profile activation, loaded scripts, and external subtitle paths instead of reinstalling packages.

If both runs explicitly report unavailable renderer support, use a full-featured package or rebuild mpv with the necessary dependency. That is the point where package replacement is justified.

6. Run a Clean Temporary Test Before Making Permanent Changes

A controlled test prevents several simultaneous changes from hiding the real fix. Use one local video, one small SRT file, and one known-good ASS file. Keep network playback, shaders, HDR profiles, custom scripts, IPC clients, and hardware decoding out of the initial test.

1. Run mpv --version and record which executable is active.
2. Open the local video with --no-config.
3. Load the SRT file explicitly and confirm ordinary text appears.
4. Load the ASS file explicitly and inspect its styling.
5. Save a verbose log if ASS fails.
6. Check whether the log indicates a missing renderer, unreadable file, missing font, or unselected track.
7. Apply only the fix matching that evidence.
8. Repeat the exact same clean command.
9. Reintroduce your configuration, scripts, profiles, shaders, and hardware decoding in stages.

Success means the ASS file displays text, positioning, colors, outlines, and expected fonts as far as the source file and installed fonts allow. Once that result survives your normal configuration, troubleshooting is complete.

7. Quick Fix Checklist

• Run a local test with --no-config before editing configuration files.
• Compare known-good SRT and ASS subtitles.
• Force --sub-visibility=yes and select a valid subtitle track.
• Check mpv.conf, profiles, bindings, and scripts for subtitle overrides.
• Use mpv --version to identify the active build.
• Capture a verbose log and search for ASS, subtitle, and font messages.
• Distinguish missing rendering from incorrect font fallback.
• Verify paths, quoting, permissions, tracks, and embedded attachments.
• Install a trusted full-featured package if the build truly lacks libass.
• Rebuild only after confirming the build system detects the libass dependency.
• Stop changing settings as soon as clean SRT and ASS tests pass.

8. Frequently Asked Questions

8.1 What does missing libass mean in mpv?

It means the mpv build lacks or cannot use the subtitle-rendering support normally responsible for SSA and ASS subtitles. The result may be missing subtitles or absent advanced styling. Confirm the diagnosis from terminal or log output because hidden tracks and missing fonts can produce similar symptoms.

8.2 Why does SRT work while ASS looks broken?

SRT is primarily timed text, while ASS can depend on advanced styling, positioning, and specific fonts. If SRT works but ASS has no styling, check whether ASS styling is disabled, whether the build has libass support, and whether required fonts are available.

8.3 Can changing hwdec, GPU drivers, or the video output fix missing libass?

Usually not. Those settings affect video decoding and presentation, not whether mpv was compiled with a subtitle-rendering library. Investigate them only if video output itself is failing. If video plays and only ASS subtitles are affected, stay focused on subtitle support, configuration, and fonts.

8.4 Will installing libass automatically repair an existing mpv binary?

Not necessarily. A prebuilt mpv binary must have been compiled with the appropriate support. If the feature was omitted at build time, installing a runtime or development package afterward may not change that binary. Install a full-featured trusted build or rebuild mpv after the dependency is detected.

8.5 How can I tell whether the problem is a missing font?

If subtitle text appears but uses the wrong typeface, has bad spacing, or shows boxes for some characters, rendering is already occurring and font fallback is likely. Check embedded attachments and legitimately installed fonts. A true renderer failure more often prevents ASS processing or display altogether.

8.6 Why do subtitles fail only for an online URL?

If local ASS subtitles work, libass is functioning. The remote source may not expose subtitles, yt-dlp may not be available to mpv, the selected stream may omit subtitle tracks, or network access may fail. Diagnose URL extraction and track availability separately from local subtitle rendering.