mpv Shader Not Loading: How to Fix It

When an mpv shader is not loading, the cause is usually narrower than it first appears. mpv may be reading a different configuration file, the glsl-shaders path may be malformed, a profile may not be active, or the selected GPU API may not support the shader. The shader can also exist but have no visible effect because it targets a specific scaling stage, requires unavailable GPU features, or is being overridden later in the configuration. The steps below isolate these possibilities without deleting your configuration or changing several unrelated settings at once.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin by testing one local video and one shader outside your normal mpv configuration. A local file removes yt-dlp, network access, playlists, authentication, and stream instability from the test. The --no-config option prevents existing profiles, scripts, input bindings, and other settings from interfering.

1.1 Verify That the Shader File Exists

Locate the shader in your file manager or terminal before launching mpv. Confirm that it is a regular file and not an empty file, shortcut, directory, archive, or text document with a hidden extra extension. For example, a Windows file displayed as example.glsl could actually be named example.glsl.txt when known extensions are hidden.

On Linux or macOS, inspect the file with a command such as:

ls -l '/full/path/to/example.glsl'

On Windows PowerShell, use:

Get-Item 'C:\full\path\to\example.glsl'

Success means the shell reports the intended file, its size is greater than zero, and the current user can read it. If this check fails, correct the filename or location before changing mpv options.

1.2 Launch a Single Shader Explicitly

Run mpv from a terminal so that errors remain visible. Replace the sample paths with absolute paths on your system.

Linux or macOS:

mpv --no-config --vo=gpu-next --glsl-shaders='/full/path/to/example.glsl' '/full/path/to/video.mkv'

Windows Command Prompt:

mpv.exe --no-config --vo=gpu-next --glsl-shaders="C:\full\path\to\example.glsl" "C:\full\path\to\video.mkv"

Windows PowerShell:

mpv.exe --no-config --vo=gpu-next --glsl-shaders='C:\full\path\to\example.glsl' 'C:\full\path\to\video.mkv'

If your installed build or GPU works with --vo=gpu rather than --vo=gpu-next, repeat the test with that output driver. Do not assume one is universally correct for every build, platform, shader, and graphics stack.

Success means mpv opens the video without a shader parsing or compilation error and the shader produces its expected visual or performance effect. Once this minimal command succeeds, stop changing GPU drivers or shader files. The remaining problem is almost certainly in the normal configuration, profile selection, command syntax, or option precedence.

2. Check the Shader Option and Configuration Path

The central option is glsl-shaders. Check its spelling, value, path format, and location in the configuration before investigating unrelated subtitle, audio, or network options.

2.1 Use the Correct Config Syntax

Inside mpv.conf, options normally omit the leading --. A typical entry is:

glsl-shaders=/full/path/to/example.glsl

Do not copy shell quoting mechanically into the config file. Shell commands, PowerShell commands, Windows batch files, and mpv.conf are parsed in different contexts. If a path contains spaces, consult the configuration-file syntax supported by your installed mpv build and verify the interpreted value through logging rather than adding layers of quotation marks at random.

Also search the entire config for every occurrence of glsl-shaders. A later assignment, profile, script, or command-line option may replace an earlier value. If multiple shaders are intended, use the list syntax accepted by your installed mpv version rather than creating repeated lines and assuming they will accumulate.

2.2 Handle Windows and Unix Paths Carefully

Unix-like systems use forward slashes and have case-sensitive paths on most Linux filesystems. Therefore, /home/user/Shaders/test.glsl and /home/user/shaders/test.glsl may be different paths.

Windows conventionally uses backslashes, such as C:\Users\Name\Shaders\test.glsl. Forward slashes can avoid some escaping ambiguity in contexts that support them, for example C:/Users/Name/Shaders/test.glsl. Do not mix path styles blindly, and remember that a backslash may be treated as an escape character by a shell or configuration parser.

Absolute paths are best for diagnosis. Relative paths depend on a working directory or configuration context that may differ when mpv is launched from a terminal, desktop shortcut, file association, or another application. Success means the same absolute path works from the minimal command and from mpv.conf.

2.3 Confirm Which Configuration File mpv Reads

A common mpv troubleshooting mistake is editing a configuration file that the running process never opens. This can happen with portable builds, multiple installations, package-manager builds, sandboxed applications, or graphical front ends that use their own configuration directory.

Launch mpv with verbose logging and inspect the beginning of the output for configuration loading information:

mpv --msg-level=all=v --log-file=mpv-shader.log '/path/to/video.mkv'

Search the resulting file for terms such as config, glsl, shader, gpu, error, and the shader filename. Success means the log identifies the expected configuration and shows the intended shader path being processed. If the expected path never appears, fix config discovery or profile activation instead of modifying the shader.

3. Check Profiles, Input Bindings, and Scripts

A shader may be configured correctly but only inside a profile that does not activate. It may also be loaded through an input binding that is never triggered, or replaced by a script after playback begins.

3.1 Verify Profile Activation

If the shader line is inside a named profile, test that profile directly:

mpv --profile=profile-name --show-profile=profile-name '/path/to/video.mkv'

The --show-profile option displays the options belonging to the named profile. It does not by itself prove that an automatic profile condition matched, so compare the displayed profile with runtime logs and the media properties on which the condition depends.

Automatic profile conditions involving resolution, file extension, protocol, HDR metadata, or other properties can fail when the property has a different value than expected. Temporarily invoke the profile explicitly. If the shader then works, stop editing the shader path and correct the profile condition.

3.2 Inspect input.conf Bindings

If a key is supposed to add, toggle, or clear a shader, verify the binding in input.conf. Check the key name, command spelling, path, and whether another binding overrides it. Run mpv from a terminal and press the key while watching for command errors.

A binding can appear ineffective if keyboard input is captured by a front end, if the command changes a property unsupported by the active video output, or if another command clears the shader list afterward. For diagnosis, load the shader from the command line first. Once that works, reconnect the binding.

3.3 Temporarily Exclude Script Interference

Scripts can change profiles, video output settings, scaling options, and shader properties. Use --no-config for the clean baseline, then add your shader explicitly. If it works, restore your normal environment in stages:

1. Add the main mpv.conf settings.
2. Add profiles one at a time.
3. Restore input.conf.
4. Restore user scripts individually.

Success is the point immediately before the shader stops working. The last restored component is the most useful place to investigate. Do not delete the entire config directory when renaming one script or commenting out one option can isolate the conflict.

4. Check GPU API Compatibility and Video Output

Custom GLSL shaders execute through GPU-based video output. A shader can fail during parsing, compilation, resource binding, or execution even when its path is correct.

4.1 Compare gpu and gpu-next

Test --vo=gpu and --vo=gpu-next separately with the same local file, shader, and --no-config baseline. The two output paths are not interchangeable in every configuration, and shader behavior can depend on the shader format and features used.

If one video output loads the shader and the other reports a compilation or unsupported-feature error, use the working output unless the shader author documents another requirement. Stop adjusting file permissions once the log proves that mpv opened the file and reached shader compilation.

4.2 Test the GPU Context and API

mpv can use different graphics APIs and platform contexts depending on the operating system, build, and driver. Vulkan, OpenGL, Direct3D-related presentation paths, Wayland, X11, and macOS graphics layers can expose different capabilities or driver behavior.

First allow mpv to select defaults. If the log identifies a GPU initialization or shader compiler failure, test another supported API or context documented for your build. Change only one variable per run and retain the log from each test. A successful test reaches normal playback and reports no shader compilation failure.

Update graphics drivers through the GPU manufacturer, operating system, or trusted distribution repository when logs show driver-level shader compiler or graphics initialization failures. Avoid codec packs and random binary bundles because GLSL shader loading is handled by the graphics and video-output pipeline, not by an untrusted collection of codecs.

4.3 Separate Hardware Decoding From Shader Loading

Hardware decoding and shader processing are related through the video pipeline, but they are not the same operation. Test with software decoding:

mpv --no-config --hwdec=no --vo=gpu-next --glsl-shaders='/path/to/example.glsl' '/path/to/video.mkv'

If the shader works with hwdec=no but not with your usual hardware-decoding mode, inspect the log for hardware frame mapping, format, or interoperation errors. You can then test a compatible hardware-decoding mode instead of concluding that the shader path is wrong.

If both tests load the shader, restore your preferred hardware decoding and stop changing it. High-bitrate playback performance may differ under software decoding, so this is primarily a diagnostic test.

4.4 Confirm That the Shader Should Produce a Visible Effect

Some shaders run only during upscaling, downscaling, chroma processing, tone mapping, or another defined processing stage. A shader designed for upscaling may show little or no difference when video is displayed at native resolution or reduced in size.

Use appropriate test content and window dimensions, and read the shader's documentation for required stages, texture formats, parameters, or companion shaders. A lack of obvious visual change is not proof that the file was ignored. The log must distinguish successful loading from parsing or compilation failure.

5. Check Permissions, Paths, and Platform Restrictions

5.1 Verify Read Permission and Sandboxing

The user running mpv must be able to read the shader and traverse its parent directories. On Linux and macOS, inspect file and directory permissions. On Windows, check file properties and access controls, particularly when the shader came from another account, a protected directory, or a network share.

Sandboxed packages may not have access to arbitrary locations even when normal filesystem permissions look correct. Move a copy of the shader to a user-accessible directory allowed by the package, or grant access using the package system's supported controls. Do not run mpv as an administrator merely to mask a path or sandbox problem.

5.2 Remove Fragile Path Variables

For the initial test, avoid environment variables, home-directory shortcuts, symbolic links, mapped drives, network locations, and relative paths. Each adds another resolution step. Use a short absolute local path containing simple characters, then reintroduce the preferred location after success.

This is especially useful when a shader works from an interactive terminal but not from a desktop launcher. The launcher may have a different working directory, environment, or user context.

5.3 Keep Unrelated Media Features Out of the Baseline

Subtitles, audio tracks, HDR processing, screenshots, IPC, playlists, and online playback can affect the broader mpv session, but they should not be mixed into the first shader test. Use a known local video with a normal video track and no dependency on external tools.

If the shader works locally but not with an online URL, the shader loader is probably functional. Investigate whether yt-dlp is available to mpv, whether the URL resolves to a playable video track, whether network access succeeds, and whether the selected stream format uses the expected video pipeline. Similarly, if a screenshot does not display the shader's effect, check the screenshot mode and whether it captures the rendered output rather than assuming the live shader failed.

6. Read Terminal Output and Create a Focused Log

Logs provide the clearest distinction between a missing file, rejected syntax, inactive profile, unsupported GPU feature, and shader that loaded without an obvious visual effect.

6.1 Capture Useful Shader Messages

Run a controlled test such as:

mpv --no-config --msg-level=all=v --log-file=shader-test.log --vo=gpu-next --glsl-shaders='/path/to/example.glsl' '/path/to/video.mkv'

Then search the log for the exact filename and for glsl, shader, compile, parse, gpu, vo, and error. Interpret the result in stages:

• If the filename never appears, mpv probably did not receive the intended option.
• If the file cannot be opened, check the path, filename, quoting, permissions, or sandbox.
• If parsing fails, verify that the file is an mpv-compatible shader and is not corrupted.
• If compilation fails, inspect the reported GLSL line and GPU capability or driver message.
• If loading succeeds, test whether the shader's activation conditions produce a visible effect.

Success means the log shows the intended video output and no load, parse, or compilation error for the shader. At that point, stop changing paths and focus only on expected shader behavior.

6.2 Use Runtime Information Carefully

mpv's stats overlay can help confirm the active renderer, frame timing, resolution, scaling conditions, and dropped frames. The track list confirms that a valid video track is selected. These are useful when a shader requires video scaling or when an online source unexpectedly provides audio only.

The stats overlay is not a universal proof that every custom shader is active. Treat it as supporting evidence and use the log as the primary diagnostic source. Likewise, subtitle-track or audio-track selection rarely fixes shader loading unless a script or profile condition explicitly depends on those properties.

7. Run a Clean Temporary Test Before Making Permanent Changes

A disciplined temporary test is safer than deleting configuration files or rewriting the entire setup. Create a small test directory containing one known video and one known compatible shader. Use absolute paths and launch mpv with --no-config.

1. Play the video without a shader and confirm normal GPU-rendered playback.
2. Add the shader path and capture a verbose log.
3. Confirm that the log names the shader and contains no relevant error.
4. Test gpu and gpu-next only if necessary.
5. Test hwdec=no only if hardware interoperation appears relevant.
6. Restore the main config, profile, scripts, and input bindings one component at a time.

Keep a record of the exact command that works. It becomes a known-good reference against which the normal launch method can be compared. Once the shader works after adding a particular configuration layer, preserve that state. Do not continue changing options merely because other unrelated mpv features could also be tuned.

8. Quick Fix Checklist

• Confirm the shader file exists, is readable, and does not have a hidden extra extension.
• Use an absolute glsl-shaders path during diagnosis.
• Use the correct path separators and shell quoting for Windows, Linux, or macOS.
• Test a local video with --no-config to remove scripts and profile conflicts.
• Check that mpv reads the configuration file you edited.
• Search for later glsl-shaders assignments that may override the first one.
• Invoke a named profile explicitly and inspect it with --show-profile.
• Compare --vo=gpu and --vo=gpu-next when compatibility is uncertain.
• Test --hwdec=no if logs suggest hardware frame interoperation problems.
• Create a verbose log and search for the shader filename, parsing errors, and compilation errors.
• Verify that the shader's intended processing stage is active and should be visually noticeable.
• Restore settings one at a time after the clean test succeeds.

9. Frequently Asked Questions

9.1 Where Should I Put mpv Shader Files?

You can store readable shader files in a user-controlled directory and reference them with glsl-shaders. A dedicated shaders directory inside your normal mpv configuration area is convenient, but an absolute path elsewhere is valid when permissions and sandbox rules allow access. During diagnosis, use an absolute path so the result does not depend on a working directory.

9.2 Why Does the Shader Work on the Command Line but Not in mpv.conf?

mpv may be reading another configuration file, a later option may override the shader list, or the config syntax may differ from shell syntax. Generate a verbose log from the normal launch method and verify the loaded config and interpreted shader path. Also inspect profiles and scripts that can change shader properties after startup.

9.3 Why Does mpv Report a Shader Compilation Error?

A compilation error means mpv found the file but the active graphics stack could not compile it. The shader may use incompatible syntax, require features unavailable through the selected GPU API, be intended for a different shader system, or contain an actual code error. Use the line information in the log, verify the shader's documented requirements, and compare supported video outputs or GPU APIs one at a time.

9.4 Can Hardware Decoding Prevent a Shader From Loading?

Hardware decoding does not normally replace shader processing, but some hardware-decoding modes can introduce frame-format or GPU-interoperation limitations. Test with --hwdec=no. If that fixes the problem, use the log to select a compatible hardware-decoding path rather than permanently disabling acceleration without evidence.

9.5 Why Is There No Visible Difference Even Though the Log Shows Success?

The shader may act only during upscaling, downscaling, tone mapping, chroma scaling, or another specific stage. Test with content and display dimensions that activate its intended operation. Some shaders also produce subtle changes. If the log confirms successful loading and no compilation errors, stop changing the path and investigate the shader's documented purpose and activation conditions.

9.6 Do yt-dlp, Subtitles, Audio, or Streams Affect GLSL Shader Loading?

They usually do not control the shader loader directly. However, an online URL may fail to provide a video track, a script may activate profiles based on media properties, or a stream may use unexpected dimensions or pixel formats. Prove the shader works with a local file first. Then troubleshoot yt-dlp discovery, network access, track selection, stream format, subtitles, or audio only if the failure occurs exclusively with that source.