mpv Vulkan Output Not Working: How to Fix It

When mpv Vulkan output is not working, the player may open a blank window, crash during startup, fall back to another graphics API, display corrupted video, or play audio without a picture. The most likely causes are an unavailable Vulkan runtime, a broken or outdated GPU driver, the wrong Vulkan device, incompatible shaders, hardware-decoding conflicts, or an option loaded from an mpv configuration, profile, script, or input binding. The safest troubleshooting method is to reproduce the problem with a clean command, inspect mpv's terminal output, and add features back one at a time.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing your normal configuration, determine whether Vulkan fails when mpv runs without user settings. This separates a system-level Vulkan problem from a configuration-specific mpv player issue.

Open Command Prompt, PowerShell, Terminal, or your preferred shell. Run mpv with a known-good local video file and explicitly request Vulkan:

mpv --no-config --vo=gpu-next --gpu-api=vulkan "path/to/test-video.mp4"

If your mpv build or hardware behaves differently with the older GPU video output, also try:

mpv --no-config --vo=gpu --gpu-api=vulkan "path/to/test-video.mp4"

Use a short, ordinary H.264 or VP9 SDR file for the first test. Avoid beginning with HDR media, an unusually high-bitrate file, an online URL, a custom shader, or a format that depends on hardware decoding. Those variables can hide the actual source of the failure.

1.1 How to interpret the clean test

• If the video appears normally, Vulkan itself works and your regular configuration is the likely cause.
• If mpv reports that Vulkan initialization failed, investigate the GPU driver, Vulkan runtime, device selection, and display environment.
• If audio plays but the window is black, test software decoding and disable shaders before blaming the Vulkan runtime.
• If the same file fails under every video output, the media file, decoder, or track selection may be responsible.
• If only online media fails, Vulkan probably is not the primary problem. Test the URL, network access, and yt-dlp integration separately.

Success means the test video produces a stable picture, responds to seeking, and closes normally. Once that happens, stop changing operating-system or driver settings. Move on to comparing the clean command with your usual mpv setup.

2. Check Options That Directly Affect Vulkan Output

mpv can load options from command-line arguments, configuration files, named profiles, scripts, and launcher shortcuts. A single stale option can make Vulkan fail even though a minimal command succeeds.

2.1 Verify the Vulkan API and video output

The central option is --gpu-api=vulkan. It tells mpv's GPU renderer to use Vulkan. Pair it with a compatible GPU video output such as --vo=gpu-next or --vo=gpu.

For a direct test, run:

mpv --no-config --vo=gpu-next --gpu-api=vulkan --hwdec=no "path/to/test-video.mp4"

The --hwdec=no option temporarily uses software decoding. It does not disable Vulkan rendering. This distinction is important because video decoding and displaying the decoded frames are separate operations.

If this works, Vulkan output is functional and the failure may be in hardware-decoder interoperability. Stop modifying the Vulkan API setting and test hardware decoding separately.

2.2 Inspect mpv.conf and active profiles

Open your mpv.conf file and look for options involving vo, gpu-api, gpu-context, vulkan-device, hwdec, profile, glsl-shader, HDR, tone mapping, interpolation, or scaling. Comment out suspicious lines individually rather than deleting the entire configuration directory.

A simple baseline configuration might contain:

vo=gpu-next
gpu-api=vulkan
hwdec=no

Do not assume this baseline is the best permanent configuration. Its purpose is to establish whether basic rendering works.

Named profiles can silently replace global options when their conditions match a file or protocol. Use the following command to inspect a profile:

mpv --show-profile=PROFILE_NAME

Also check launcher scripts, desktop shortcuts, shell aliases, and file-manager associations. They may append options that do not appear in mpv.conf.

2.3 Check vulkan-device selection

Systems with integrated and discrete GPUs can expose more than one Vulkan device. If vulkan-device names an unavailable GPU, or a driver update changes the reported device name, mpv may fail during graphics initialization.

First remove any explicit vulkan-device setting and let mpv select a device automatically. Test again with --no-config. If automatic selection works, your previous device override was incorrect or no longer necessary.

Use verbose terminal output to see which adapters mpv detects and selects:

mpv --no-config --vo=gpu-next --gpu-api=vulkan --msg-level=all=v "path/to/test-video.mp4"

If you need a specific GPU, use the device name reported by your installed mpv and Vulkan environment rather than guessing it. Success means the log identifies the intended adapter and video renders without initialization or device-lost errors.

2.4 Disable custom shaders and demanding GPU features

GLSL shaders are not automatically compatible with every renderer, mpv build, driver, or shader chain. A shader can compile under one graphics backend and fail under another. Temporarily remove every glsl-shader or glsl-shaders option, including shaders loaded by profiles or scripts.

Also test without interpolation, advanced scaling, HDR processing overrides, user hooks, and custom tone-mapping settings. Start with:

mpv --no-config --vo=gpu-next --gpu-api=vulkan --hwdec=no "path/to/test-video.mp4"

If the baseline succeeds, add one shader or GPU feature at a time. Play and seek through the file after each addition. Stop as soon as the failure returns because the last addition is the strongest suspect.

2.5 Test hardware decoding separately

Hardware decoding can fail when the decoder cannot share frames correctly with the Vulkan renderer. This can depend on the operating system, GPU vendor, driver, codec, bit depth, and mpv build.

Compare these tests:

mpv --no-config --vo=gpu-next --gpu-api=vulkan --hwdec=no "path/to/test-video.mp4"
mpv --no-config --vo=gpu-next --gpu-api=vulkan --hwdec=auto "path/to/test-video.mp4"

If software decoding works and --hwdec=auto fails, leave hardware decoding off temporarily or test a hardware-decoding method supported by your platform. Do not install an untrusted codec pack. mpv normally uses its bundled or linked decoding stack, and random codec packages rarely repair Vulkan interoperability.

3. Rule Out Tracks, Scripts, Streams, and Unrelated Playback Failures

A black window does not always mean Vulkan initialization failed. The selected file may have no usable video track, a script may alter playback, or an online extractor may fail before mpv receives media.

3.1 Confirm the video track and subtitle behavior

Use mpv's track list or cycle through tracks with the default controls. In the terminal log, confirm that a video stream was detected and selected. A file containing only audio, a playlist entry with a dead video URL, or an explicit vid=no option can produce audio without video.

Test without subtitles if the blank display appears only when a particular subtitle file is loaded:

mpv --no-config --vo=gpu-next --gpu-api=vulkan --sid=no "path/to/test-video.mkv"

Subtitle rendering is usually not the cause of Vulkan initialization failure, but malformed external subtitles, unusually large subtitle textures, or subtitle-related scripts can expose a rendering or memory problem. If disabling subtitles fixes playback, test the same video with a simple subtitle track before changing GPU drivers.

3.2 Disable scripts and input-driven option changes

The --no-config test prevents normal user configuration from loading, which also makes it valuable for identifying script-related behavior. Review scripts that change profiles, shaders, video outputs, aspect ratio, tracks, screenshots, or playback URLs.

Check input.conf for bindings that run commands such as set vo, set gpu-api, cycle-values, apply-profile, or shader toggles. A binding may make the problem appear intermittent because it changes an option only after a key is pressed.

Success means playback remains stable in a clean test and fails only after a particular script, profile, or binding is restored. Keep that component disabled until you verify its documented requirements and current compatibility.

3.3 Separate yt-dlp and network problems from Vulkan

For an online URL, first test a local file with the same Vulkan command. If local video works, the graphics output is probably healthy.

Then run the URL with verbose logging and inspect whether mpv can invoke yt-dlp, resolve the media formats, and access the selected stream. Confirm that the yt-dlp executable is installed through a trusted source and is available on the expected path. Shell quoting also matters because characters such as ampersands, question marks, and percent signs may be interpreted by the shell.

If mpv reports an extractor, HTTP, authentication, DNS, or timeout error before opening a video stream, fix that problem first. Vulkan cannot display frames that were never downloaded or decoded.

3.4 Treat screenshot failures as a separate path

If video plays but screenshots are black, missing, or fail to save, the Vulkan output itself may be working. Check the screenshot directory, filename template, filesystem permissions, available disk space, image format, and screenshot-related bindings. Test with mpv's default screenshot command and a writable directory before modifying renderer options.

4. Check the Vulkan Runtime, GPU Driver, and Operating System

If Vulkan fails even with --no-config, the cause is likely outside your normal mpv configuration. Focus on whether the operating system can expose a usable Vulkan device to mpv.

4.1 Verify Vulkan driver and runtime availability

Vulkan requires a compatible GPU driver and loader. Updating the operating system alone does not always install the correct vendor graphics driver. Obtain drivers from the GPU manufacturer or your operating system's trusted package repositories.

• On Windows, confirm that the installed Intel, AMD, or NVIDIA driver supports the GPU and provides Vulkan components.
• On Linux, verify that the correct Mesa or proprietary driver packages are installed for the active GPU.
• On macOS, Vulkan is not a native graphics API. An mpv build must include or use an appropriate Vulkan portability implementation, commonly based on MoltenVK.

Restart after a driver installation when the platform or installer requires it. Then repeat the exact minimal command. Success means mpv creates a Vulkan device and displays the test file without falling back or crashing.

4.2 Check the display server and session environment

On Linux, behavior can differ between X11 and Wayland sessions because mpv must create a compatible window and presentation surface. Do not force a gpu-context copied from another computer unless you know it matches your active session.

Test without an explicit context first. If mpv works in one desktop session but not another, inspect the driver and compositor support for that session. Remote desktop, containers, SSH sessions, virtual machines, and headless environments may not expose the same Vulkan device or display surface as a local graphical login.

4.3 Consider permissions and hybrid-GPU routing

On Linux, device-node permissions or container restrictions can prevent access to the GPU. On hybrid laptops, the application may start on an integrated GPU even when a discrete GPU was expected. Use your operating system or GPU vendor's supported application-selection method, then check mpv's verbose log to confirm the selected device.

Avoid broad permission changes such as making graphics devices writable by every user. Use the distribution's standard groups, session management, and device rules instead.

4.4 Test a fallback renderer

A fallback test reveals whether playback works when Vulkan is removed from the rendering path. On Linux and macOS, try OpenGL:

mpv --no-config --vo=gpu-next --gpu-api=opengl "path/to/test-video.mp4"

On Windows, a D3D11-based path may be available depending on the selected mpv video output and build. You can also let mpv choose a supported API automatically by removing the forced gpu-api=vulkan option.

If OpenGL or D3D11 works while Vulkan consistently fails, keep the working backend as a practical temporary fix. The media file and core decoder are probably usable, so further troubleshooting should focus on the Vulkan driver, runtime, device, or Vulkan-specific options.

5. Capture Useful Diagnostic Output

Terminal output is more useful than repeatedly changing unrelated options. Run mpv from a terminal so initialization errors remain visible after the window closes.

5.1 Enable verbose messages

Use a broad verbose level for a short test:

mpv --no-config --vo=gpu-next --gpu-api=vulkan --msg-level=all=v "path/to/test-video.mp4"

Look for messages mentioning Vulkan instance creation, physical devices, selected adapters, surface creation, shader compilation, hardware decoding, unsupported formats, or device loss. The first specific error is often more valuable than later errors caused by the initial failure.

5.2 Save a reproducible log

Write output to a file when the terminal closes too quickly or when you need to compare tests:

mpv --no-config --vo=gpu-next --gpu-api=vulkan --msg-level=all=v --log-file=mpv-vulkan.log "path/to/test-video.mp4"

Review the log before sharing it. Remove private file paths, signed stream URLs, usernames, tokens, or other sensitive information. Keep the complete initialization sequence around the error rather than posting only the final line.

5.3 Use profiles, stats, and track information carefully

--show-profile helps reveal what a named profile applies. During successful playback, mpv's stats overlay, commonly opened with the i key under default bindings, can show rendering, decoding, frame timing, and dropped-frame information. The track list confirms whether a video stream is actually selected.

These tools have different purposes. The stats overlay helps with performance after rendering starts, while the terminal log is the better tool when Vulkan cannot initialize at all.

6. Run a Clean Temporary Test Before Making Permanent Changes

Changing the driver, renderer, hardware decoder, shaders, profiles, and scripts at the same time makes the result impossible to interpret. Use a controlled sequence instead.

1. Choose one known-good local SDR video.
2. Run it with --no-config, Vulkan, and software decoding.
3. If it works, enable --hwdec=auto and retest.
4. Add your normal profile without adding scripts or shaders.
5. Add custom shaders individually.
6. Restore scripts one at a time.
7. Test HDR, high-bitrate media, subtitles, network streams, and online URLs only after local playback is stable.

After every step, play for long enough to seek, pause, resize the window, toggle fullscreen, and reach a representative section of the file. Success is not merely the absence of an immediate crash. It is stable video output with normal controls and no recurring device or shader errors.

When a step fails, revert only the last change. Stop there and investigate that option or component. Do not continue adding variables.

7. Quick Fix Checklist

• Test a normal local video with --no-config --vo=gpu-next --gpu-api=vulkan --hwdec=no.
• Remove any forced vulkan-device value and allow automatic GPU selection.
• Disable custom shaders, interpolation, HDR overrides, and user hooks.
• Compare --hwdec=no with --hwdec=auto.
• Inspect mpv.conf, profiles, scripts, shortcuts, and input.conf.
• Update the GPU driver from a trusted vendor or operating-system source.
• Confirm that a Vulkan runtime and supported device are available.
• Test OpenGL or D3D11 to isolate a Vulkan-specific failure.
• Use --msg-level=all=v and --log-file to capture the first error.
• Test local playback before diagnosing yt-dlp or a network stream.

8. Frequently Asked Questions

8.1 Why does mpv play audio but show a black Vulkan window?

The video track may be disabled, decoding may have failed, hardware-decoded frames may not interoperate with Vulkan, or a shader may fail after the window is created. Test a known-good file with --no-config and --hwdec=no. If that works, restore hardware decoding and shaders separately.

8.2 Should I permanently use OpenGL instead of Vulkan?

Using OpenGL is a reasonable practical fix if it is stable and provides the features and performance you need. Vulkan is not mandatory for normal mpv playback. Keep OpenGL or D3D11 while investigating the Vulkan driver or runtime rather than accepting crashes or blank output.

8.3 Does --no-config delete or reset my settings?

No. --no-config temporarily prevents normal configuration loading for that mpv process. It does not delete your files. This makes it safer than removing an entire configuration folder.

8.4 Can the wrong vulkan-device setting stop mpv from opening?

Yes. An explicit device name can become invalid after hardware, driver, or environment changes. Remove the override and let mpv select automatically. Use verbose output to identify the device mpv actually detects before adding a new override.

8.5 Why does Vulkan work for SDR video but fail with HDR?

HDR adds requirements involving bit depth, color conversion, tone mapping, display capabilities, driver behavior, and sometimes hardware decoding. First establish stable SDR playback. Then test the HDR file without custom shaders, forced tone-mapping options, or hardware decoding. Add each feature back separately.

8.6 Is yt-dlp responsible for a blank Vulkan window?

It can cause an online video to produce no playable stream, but it does not normally control Vulkan rendering. If local files work, inspect the yt-dlp path, URL quoting, extractor output, network access, and selected media formats. Treat extraction errors and Vulkan errors as separate problems.