mpv OpenGL Output Not Working: How to Fix It

When mpv OpenGL output is not working, the player may open to a black window, display corrupted colors, flicker, crash during startup, or report that it cannot initialize a video output or GPU context. The most likely causes are an unsupported OpenGL implementation, an incompatible gpu-context, a graphics-driver problem, a compositor conflict, hardware decoding, or an option loaded from an mpv configuration, profile, script, or shader. Start with a clean command and change one variable at a time. As soon as normal video appears consistently, stop changing settings and restore optional features individually.

1. Confirm the Symptom With a Minimal Clean mpv Command

Before editing mpv.conf, determine whether OpenGL fails in a clean session. Use a short local video stored on a local disk. A familiar H.264 or other ordinary SDR file is preferable to HDR media, an online URL, a playlist, or an unusually high-bitrate file because it removes unrelated variables.

Run the following command in a terminal:

mpv --no-config --vo=gpu --gpu-api=opengl "test-video.mp4"

On Windows, run it from PowerShell or Command Prompt after changing to the directory containing mpv.exe, or provide the complete path to the executable and file. On Linux and macOS, use the correct installed command and quote paths containing spaces.

This test deliberately bypasses the normal configuration and requests GPU rendering through OpenGL. Success means a stable picture appears, playback advances normally, and the terminal does not report a failure to create a GPU context. If that happens, basic OpenGL output works. Stop investigating the operating system and inspect your normal configuration instead.

If the minimal command fails, compare it with automatic GPU API selection:

mpv --no-config --vo=gpu "test-video.mp4"

If automatic selection works but the forced OpenGL command fails, another graphics API or context is working while OpenGL is not. That distinction points toward OpenGL support, the selected context, or the graphics driver rather than the media file itself.

1.1 Distinguish an OpenGL failure from a decoding failure

A video-output failure normally produces messages about vo, GPU initialization, OpenGL, context creation, shaders, or swap chains. A decoding failure instead mentions an unsupported codec, invalid packets, or a decoder that could not be opened. Audio playing behind a black window can occur in either case, so terminal output is more useful than the visible symptom alone.

Test a second ordinary local file if the first file fails. If only one file fails, OpenGL probably is not the root cause. That file may use an unsupported codec, damaged timestamps, an unusual pixel format, HDR metadata, or dimensions beyond the hardware's practical limits.

2. Check Options That Directly Affect OpenGL Output

If clean playback succeeds, restore your normal setup carefully. Configuration can be loaded from mpv.conf, profiles, command-line aliases, shortcuts, input bindings, scripts, and frontend applications. A setting may also be supplied by a launcher without appearing in your main configuration file.

2.1 Inspect the video output and GPU API

Look for options such as vo=, gpu-api=, and gpu-context=. A forced context copied from another operating system can prevent initialization. Start with the least restrictive configuration:

vo=gpu
gpu-api=opengl

Temporarily remove or comment out any explicit gpu-context line so mpv can choose an available context. If automatic selection works, keep it unless you have a demonstrated reason to force a platform-specific context.

If your build uses gpu-next successfully, it can also be tested with OpenGL where supported:

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

Do not assume that gpu and gpu-next will behave identically on every system. Test the output supported by your installed mpv build and confirm available options with mpv --vo=help.

2.2 Test GPU context selection

The correct context depends on the operating system, window system, mpv build, and graphics stack. Linux installations may involve X11 or Wayland contexts. Windows commonly uses a Windows OpenGL context, while macOS builds rely on the contexts provided by that platform and build configuration.

First let mpv select automatically:

mpv --no-config --vo=gpu --gpu-api=opengl --gpu-context=auto "test-video.mp4"

Then inspect mpv --gpu-context=help for values actually recognized by your build. Test only relevant listed contexts. Do not paste a context name from an old forum post without verifying that your installed build supports it.

Success means one context opens the video reliably without context-creation errors, flickering, or a black frame. Once you find a working context, stop testing contexts. You can keep automatic selection if it produces the same reliable result.

2.3 Disable shaders and advanced rendering options

Custom GLSL shaders can fail to compile, exceed older GPU capabilities, consume too much video memory, or expose driver bugs. Temporarily test without user configuration, or comment out options including glsl-shaders, shader hooks, interpolation, complex scalers, debanding, and user shader directories.

mpv --no-config --vo=gpu --gpu-api=opengl "test-video.mp4"

If you need to test the rest of your configuration, disable only the shaders in a temporary copy of the relevant profile. A successful test produces normal video without shader compilation errors. Restore one shader or rendering feature at a time until the problem returns. The last restored item is the strongest suspect.

2.4 Separate hardware decoding from OpenGL rendering

Hardware decoding and OpenGL output are related but separate stages. A decoder may fail to transfer frames into a form the selected GPU output can display. Test software decoding:

mpv --no-config --vo=gpu --gpu-api=opengl --hwdec=no "test-video.mp4"

If this works while --hwdec=auto does not, OpenGL itself can render video, but the hardware-decoding path is incompatible or unstable. Keep hwdec=no temporarily, update the graphics driver through a trusted operating-system or hardware-vendor channel, and later test the hardware decoders listed by mpv --hwdec=help.

Success is smooth, correctly colored playback without decoder initialization or frame-mapping errors. Do not keep changing the output driver after software decoding proves that the output works.

2.5 Check profiles, scripts, bindings, subtitles, and tracks

A profile may activate only for 4K, HDR, fullscreen, or particular file extensions. A script can also change properties after playback starts. Temporarily move individual third-party scripts out of the script directory, or use --no-config to establish whether they are involved. Avoid deleting the entire configuration folder.

Subtitle rendering rarely prevents OpenGL initialization, but complex ASS subtitles and unusually large subtitle textures can reveal GPU or driver limitations. Press the subtitle-cycle binding or run a test with subtitles disabled:

mpv --no-config --sid=no --vo=gpu --gpu-api=opengl "test-video.mkv"

Use --aid=no for a temporary audio-free test if playback hangs while opening the audio device. An audio-backend failure is not an OpenGL failure, but it can obscure the diagnosis. Also inspect the track list to confirm that mpv selected a real video track rather than an attached image or audio-only item.

3. Check the Operating System and Graphics Stack

3.1 Verify OpenGL driver support

mpv depends on the OpenGL implementation exposed by the installed graphics driver. A generic fallback driver, incomplete virtual-machine graphics stack, remote desktop session, or broken vendor installation may expose insufficient capabilities or fail during context creation.

On Windows, obtain graphics drivers through Windows Update or the official Intel, AMD, NVIDIA, or computer-manufacturer support channel. On Linux, prefer packages supplied by the distribution or the GPU vendor's documented repository. On macOS, graphics drivers are delivered as part of operating-system updates. Avoid random driver archives and codec packs because codec packs do not repair OpenGL.

Restart after a driver replacement when the operating system requires it, then repeat the minimal clean command. Success means the forced OpenGL test now starts without context or shader-version errors. If it works, stop altering mpv options and restore your normal configuration cautiously.

3.2 Account for old Intel graphics limitations

Older Intel GPUs and legacy drivers can have limited OpenGL feature support, unreliable hardware decoding, low texture-size limits, or bugs triggered by advanced shaders and high-resolution video. The practical first test is software decoding with no custom shaders and default scaling.

If that combination works, keep the simple rendering path. Test higher-cost features individually rather than enabling an entire quality preset. If basic forced OpenGL still fails on a fully updated legacy system, a fallback output or automatically selected non-OpenGL API may be more reliable than attempting to force unsupported features.

3.3 Test the desktop compositor and display server

Desktop compositors can affect fullscreen transitions, synchronization, transparency, and presentation timing. If video appears only in windowed mode, flickers in fullscreen, or becomes black after changing displays, disable optional compositor effects temporarily. Examples include blur, transparency, third-party overlays, game overlays, recording overlays, and experimental variable-refresh settings.

On Linux, test the session's native display path and, when both are installed, compare X11 and Wayland using context values reported by --gpu-context=help. Do not force an X11 context in a Wayland-only environment or the reverse. Success means stable windowed and fullscreen playback under one supported session and context combination.

3.4 Rule out path, permission, and shell errors

A shell can interpret spaces, ampersands, question marks, brackets, and quotation marks. Quote local paths and URLs. Confirm that the current user can read the media file and configuration files and can write to any requested screenshot or log directory.

A failed screenshot does not necessarily mean video output failed. Test screenshots with a simple writable directory and a basic format. Likewise, a missing file caused by incorrect quoting is not an OpenGL problem, even if mpv closes immediately.

3.5 Separate online playback from rendering

For online URLs, first confirm that the same OpenGL command plays a local file. If local playback works, investigate network access, TLS errors, site support, authentication, and the external downloader path. mpv commonly relies on yt-dlp for supported web pages, while direct media streams may be handled internally.

Use an officially installed and current yt-dlp executable, verify that mpv can find it, and test the URL directly with the tool's documented diagnostics when appropriate. Do not treat a site extraction error, expired stream token, geo-restriction, DRM-protected service, or unavailable playlist entry as an OpenGL failure.

4. Use mpv Diagnostics to Identify the Failing Stage

Terminal output usually reveals whether failure occurs during demuxing, decoding, GPU context creation, shader compilation, audio initialization, or presentation. Run mpv from a terminal rather than opening the file only through a graphical shell.

4.1 Increase useful logging

Start with a readable level for relevant components:

mpv --no-config --vo=gpu --gpu-api=opengl --msg-level=vo=debug,gpu=debug "test-video.mp4"

If your build uses different component names, use general verbose output:

mpv --no-config -v --vo=gpu --gpu-api=opengl "test-video.mp4"

Save a log when the terminal closes too quickly:

mpv --no-config -v --log-file=mpv-opengl.log --vo=gpu --gpu-api=opengl "test-video.mp4"

Search for the first meaningful failure rather than the last cascade of errors. Messages naming context creation, unsupported OpenGL versions or extensions, shader compilation, frame mapping, or a failed video-output initialization are directly relevant.

4.2 Inspect profiles and runtime state

Use --show-profile=PROFILE_NAME to inspect a named profile before applying it. Review conditional profiles carefully because they can activate according to resolution, protocol, filename, or another property. Also check shell aliases, desktop shortcut arguments, and frontend settings that append options.

During playback, mpv's stats overlay can show the active video output, decoder, dropped frames, display synchronization, and performance information, depending on the build and overlay page. The track list confirms the selected video, audio, and subtitle tracks. These tools help distinguish a rendering failure from a missing or disabled track.

5. Run a Clean Temporary Test Before Permanent Changes

Use a small test matrix instead of changing many settings simultaneously. Record whether each command works:

1. Test --no-config --vo=gpu --gpu-api=opengl --hwdec=no with an ordinary local SDR file.
2. Repeat with --hwdec=auto.
3. Test automatic GPU API selection by removing --gpu-api=opengl.
4. Test a relevant context listed by --gpu-context=help.
5. Load the normal configuration without third-party scripts and shaders.
6. Restore one script, shader, profile, or advanced option at a time.

This sequence isolates the layer responsible for the mpv player issue. If step one fails, concentrate on OpenGL support, the context, drivers, the display server, and fallback output. If step one works but step two fails, investigate hardware decoding. If both work until the normal configuration returns, the fault is in configuration, scripts, profiles, or shaders.

5.1 Use a fallback output driver for diagnosis

List available outputs with:

mpv --vo=help

Test an available non-OpenGL or software-oriented output supported by your build. Output names differ by platform and build, so select only from the displayed list. A basic fallback may have reduced scaling quality, color-management capability, HDR handling, or performance, but it can prove that demuxing and decoding work.

If a fallback displays the same file while forced OpenGL fails, the evidence points to the OpenGL or GPU presentation path. A fallback is a valid temporary workaround, especially on legacy hardware, but automatic GPU selection may provide a better long-term result when another modern graphics API is available.

6. Quick Fix Checklist

• Test a normal local SDR file with --no-config.
• Force --vo=gpu --gpu-api=opengl to confirm the exact failure.
• Remove a forced gpu-context and try automatic selection.
• Check supported contexts with mpv --gpu-context=help.
• Disable custom GLSL shaders and expensive rendering presets.
• Use --hwdec=no to separate decoding from output.
• Update the GPU driver from an official trusted source.
• Temporarily disable compositor effects, overlays, and experimental display features.
• Compare windowed and fullscreen playback.
• Inspect profiles, scripts, aliases, shortcuts, and frontend arguments.
• Quote paths and URLs and verify file permissions.
• Test online playback only after a local file works.
• Capture verbose output with --log-file.
• Try an output listed by --vo=help as a diagnostic fallback.
• Stop changing settings once playback is stable and reproducible.

7. Frequently Asked Questions

7.1 Why does mpv play audio but show a black OpenGL window?

Audio can continue when video-output initialization, frame transfer, shader compilation, or presentation fails. Test with --no-config --vo=gpu --gpu-api=opengl --hwdec=no. If video appears, the likely cause is hardware decoding or configuration rather than basic OpenGL rendering.

7.2 Should I force gpu-context?

Usually, automatic selection is the safest starting point. Force a context only when the automatic choice is demonstrably wrong and the desired value appears in mpv --gpu-context=help. A context that works on another operating system or display server may be invalid on yours.

7.3 Can custom shaders cause OpenGL output to stop working?

Yes. A shader may require capabilities the GPU or driver does not provide, fail to compile, or consume excessive resources. Test without configuration, then restore shaders one at a time. Stop when the failing shader is identified and leave it disabled or replace it with a compatible alternative.

7.4 Why does OpenGL fail only with HDR or high-bitrate video?

HDR can involve higher bit depth, tone mapping, large textures, and more demanding shaders. High-bitrate or high-resolution media can also stress decoding and frame transfer. Test software decoding, no shaders, and an SDR file. If SDR works, the limitation is likely in the advanced media path rather than basic OpenGL initialization.

7.5 Is yt-dlp responsible for a black screen?

It can be responsible when an online page fails to resolve into a playable stream, but it does not control OpenGL rendering. Confirm local playback first. If local OpenGL playback works, examine yt-dlp discovery, network errors, URL quoting, stream availability, and site support.

7.6 When should I use a fallback output?

Use a fallback when forced OpenGL consistently fails but another listed output displays the file, or when legacy hardware cannot provide a reliable OpenGL implementation. Treat it as a workaround or diagnostic result. If automatic GPU selection provides stable playback with acceptable quality, there is no need to keep forcing OpenGL.