mpv GPU API Selection Wrong: How to Fix It

When mpv selects the wrong GPU API, rendering backend, or graphics adapter, the symptoms can include a black window, unexpectedly high CPU usage, dropped frames, broken HDR output, poor shader performance, or playback running on an integrated GPU instead of a discrete GPU. The most likely causes are an incompatible gpu-api or gpu-context setting, an adapter override, a profile or script changing options, hybrid-graphics routing, or a driver and display-server limitation. The safest approach is to reproduce the problem without your normal configuration, identify the backend mpv actually selected, and then add only the smallest necessary override.

1. How Do You Confirm That mpv Is Selecting the Wrong GPU API?

Start by separating a real GPU-selection problem from an unrelated decoding, subtitle, audio, network, or media-file issue. Open a terminal and play a known-good local video with no user configuration:

mpv --no-config --vo=gpu-next sample.mkv

If your build or setup does not work with gpu-next, test the established GPU output driver instead:

mpv --no-config --vo=gpu sample.mkv

Use a short local file that normally plays correctly. A local test removes yt-dlp, authentication, network speed, playlists, and remote-server behavior from the diagnosis. It also reduces the chance that a damaged or unusual stream is being mistaken for an output API problem.

1.1 Test the available gpu-api values

The gpu-api option chooses the graphics API used by mpv's GPU video output. Common values include auto, opengl, vulkan, and, on supported Windows builds, d3d11. Availability depends on the operating system, build features, drivers, and selected video output.

Test one value at a time:

• mpv --no-config --vo=gpu-next --gpu-api=auto sample.mkv
• mpv --no-config --vo=gpu-next --gpu-api=opengl sample.mkv
• mpv --no-config --vo=gpu-next --gpu-api=vulkan sample.mkv
• mpv --no-config --vo=gpu-next --gpu-api=d3d11 sample.mkv on Windows

Do not assume that Vulkan or D3D11 is automatically better than OpenGL. The correct choice is the API that works reliably with your driver, window system, display pipeline, shaders, and HDR requirements. Success means the video window opens, playback remains stable, seeking works, and the terminal or log identifies the requested backend without reporting a fallback or initialization failure. Once one clean command works, stop switching APIs and investigate why your normal configuration behaves differently.

1.2 Distinguish the API from the device

The API and the physical GPU are separate choices. Setting gpu-api=vulkan requests Vulkan, but it does not necessarily guarantee that mpv will use the discrete GPU you intended. Likewise, selecting D3D11 does not by itself choose a particular Windows adapter.

The gpu-context option is another distinct setting. It controls the platform-specific rendering context, such as a Windows, Wayland, or X11 context. Normally, auto is appropriate. Force a context only when logs show that automatic context selection is failing or choosing an unsuitable display path.

2. Check Every Setting That Can Override GPU Selection

If a clean command succeeds but ordinary playback fails, your configuration is the leading suspect. Do not delete your configuration directory. Inspect it or temporarily bypass it with --no-config, then narrow the issue down carefully.

2.1 Inspect mpv.conf and included files

Search your mpv configuration files for these option names:

• vo
• gpu-api
• gpu-context
• d3d11-adapter
• vulkan-device
• hwdec
• profile and include

A conservative starting configuration is:

vo=gpu-next
gpu-api=auto
hwdec=auto-safe

Do not copy those lines blindly if your existing setup already works with vo=gpu or deliberately uses software decoding. First test them on the command line. Command-line tests are temporary and make rollback immediate.

Check included configuration files as well as the main mpv.conf. An included file loaded later can replace an earlier setting. Duplicate options are especially confusing because the final effective value may not be the one nearest the top of the main file.

2.2 Check profiles and automatic conditions

Profiles can silently change rendering options for fullscreen playback, specific protocols, file extensions, HDR content, screen dimensions, or other conditions. Look for profile sections containing GPU-related settings. Also inspect conditional profiles created with profile-cond.

To inspect a named profile, run:

mpv --show-profile=profile-name

This displays the options associated with that profile. If removing or disabling one GPU-related line makes normal playback match the clean test, the profile was the cause. Stop there rather than rewriting unrelated subtitle, audio, or network settings.

2.3 Review input bindings and scripts

An input.conf binding can apply a profile or change properties during playback. Search it for commands such as apply-profile, set, cycle-values, or script messages associated with rendering behavior.

Scripts can also set options at startup or after a file loads. Test without configuration first, then temporarily disable individual scripts rather than removing the entire configuration folder. If the problem occurs only with scripts enabled, restore them one at a time until the responsible script is identified.

2.4 Keep adjacent playback settings in perspective

Subtitle style, subtitle tracks, audio tracks, screenshots, yt-dlp, and stream URLs normally do not choose the GPU API. However, they can create symptoms that resemble a rendering failure. A complex subtitle renderer or shader can increase GPU load. A screenshot format may fail while playback remains healthy. A missing audio device can stop or disrupt playback even though the graphics backend initialized correctly. An online URL can fail before video reaches the renderer.

Use a plain local file with scripts and shaders disabled before blaming GPU selection. If local playback works but an online URL does not, inspect yt-dlp and network messages. If only one HDR file fails, compare it with another HDR sample and an SDR file. If only one subtitle track causes severe slowdown, test with --sid=no. These checks prevent unrelated settings from obscuring the output API diagnosis.

3. Select the Correct Adapter on Windows

On Windows, D3D11 adapter selection is relevant when multiple graphics adapters are available. This is common on laptops with integrated and discrete GPUs, desktop systems with multiple cards, and remote or virtual display configurations.

3.1 Discover and set the D3D11 adapter

Ask mpv to report valid adapter choices rather than guessing a device name:

mpv --no-config --vo=gpu-next --gpu-api=d3d11 --d3d11-adapter=help sample.mkv

Use the reported adapter name in a new test. Quote names containing spaces:

mpv --no-config --vo=gpu-next --gpu-api=d3d11 --d3d11-adapter="Adapter Name" sample.mkv

If this works consistently, place the tested settings in mpv.conf:

vo=gpu-next
gpu-api=d3d11
d3d11-adapter=Adapter Name

Success means the log identifies D3D11 and the intended adapter, with no adapter-creation failure. Stop changing settings when playback, seeking, fullscreen transitions, HDR if applicable, and your normal shaders work correctly.

3.2 Configure hybrid graphics routing

Windows can assign a preferred GPU to an application through its system graphics settings. Add the exact mpv.exe you launch and choose the appropriate power preference. This matters when several mpv executables exist in different folders or when a frontend launches a different binary.

The operating system's GPU preference and mpv's D3D11 adapter setting can interact. For initial testing, use one clear method at a time. If Windows routing reliably starts mpv on the desired GPU, an explicit adapter line may be unnecessary. If routing is inconsistent, an mpv adapter setting can make the choice observable and reproducible.

Do not judge selection solely from overall GPU utilization. Video decoding, rendering, copying, and display presentation can use different GPU engines. Confirm the adapter in mpv's log and, if needed, examine the relevant GPU engine in Task Manager.

4. Select a Vulkan Device and Handle Linux GPU Routing

4.1 Choose a Vulkan device explicitly

On systems exposing more than one Vulkan device, list the choices before configuring one:

mpv --no-config --vo=gpu-next --gpu-api=vulkan --vulkan-device=help sample.mkv

Then test the exact reported name:

mpv --no-config --vo=gpu-next --gpu-api=vulkan --vulkan-device="Device Name" sample.mkv

If the command succeeds and the log confirms the intended device, add the option to your configuration. Device names can change after hardware or driver changes, so revisit this override if mpv later reports that the named device cannot be found.

4.2 Use Linux environment variables carefully

On Linux hybrid-graphics systems, the environment used to launch mpv can influence device selection. Mesa commonly supports DRI_PRIME for selecting a non-default GPU. A temporary test may look like:

DRI_PRIME=1 mpv --no-config --vo=gpu-next --gpu-api=vulkan sample.mkv

NVIDIA PRIME render offload configurations may use variables such as __NV_PRIME_RENDER_OFFLOAD=1, with additional variables required for some OpenGL setups. Distribution-provided launch helpers may be preferable because they apply the correct environment for that system.

Set variables only for the test command first. Do not add them globally to your shell profile until you know they solve the problem without affecting other applications. Variables that select Vulkan ICD files are advanced diagnostic tools and can hide installed drivers if set incorrectly. Prefer mpv's vulkan-device option or your distribution's supported GPU-offload method when possible.

4.3 Account for Wayland and X11

A GPU may support an API while the chosen display context still fails. On Linux, note whether the session is Wayland or X11 and inspect the log for the context mpv selected. Test automatic selection first. If the log shows a specific context failure, compare a targeted gpu-context test using a value supported by your mpv build.

Success means mpv creates the rendering context on the active display server, reports the intended GPU, and presents frames normally. If Vulkan initializes but window creation fails, the issue may be the display context rather than the Vulkan device itself.

5. Check Drivers, Permissions, Decoding, and Media Limits

GPU API selection relies on working operating-system drivers. Install graphics drivers through Windows Update, the hardware vendor, or your Linux distribution's package system. On macOS, graphics support is delivered with the operating system. Avoid random driver bundles, codec packs, or unofficial binary sites.

Hardware decoding and GPU rendering are related but different. The hwdec option controls video decoding, while gpu-api controls rendering. A file can decode in software and still render through Vulkan, OpenGL, or D3D11. Conversely, a hardware decoder can fail even though the rendering backend is healthy.

Compare these tests:

• mpv --no-config --vo=gpu-next --gpu-api=auto --hwdec=no sample.mkv
• mpv --no-config --vo=gpu-next --gpu-api=auto --hwdec=auto-safe sample.mkv

If software decoding works but hardware decoding fails, keep the working output API and troubleshoot the decoder separately. High CPU usage with hwdec=no is expected and does not prove that mpv selected the wrong rendering API.

Permissions are less commonly responsible for adapter selection, but they can affect access to GPU device nodes on Linux or files and external tools on any system. Avoid running mpv as an administrator or root as a routine fix. Correct the specific installation, group, sandbox, or file-access issue reported in the log.

6. Use Logs and Runtime Information to Verify the Selected Backend

Do not rely on visual impressions alone. Capture a verbose log from a short reproduction:

mpv --no-config --msg-level=all=v --log-file=mpv-gpu.log --vo=gpu-next --gpu-api=auto sample.mkv

Search the log for terms including gpu, vulkan, d3d11, opengl, adapter, device, context, hwdec, fallback, failed, and error. The useful lines identify the selected API, rendering context, device or adapter, driver, and any failed initialization attempt.

During playback, press i for mpv's statistics overlay in standard configurations. The overlay can help confirm decoding mode, dropped frames, display synchronization, and performance. It may not expose every device-selection detail, so the terminal output or log remains authoritative.

The track list is useful when the apparent failure occurs only with a particular video, audio, or subtitle track. Check the on-screen track information or terminal output, and test explicit selections such as --sid=no or --aid=no when appropriate. This does not select a GPU, but it can reveal that the mpv player issue originates in a track rather than the output backend.

When comparing normal and clean runs, create two logs and inspect the first point where they differ. If the clean run selects Vulkan on the discrete GPU while the configured run selects OpenGL on the integrated GPU, look immediately before those lines for loaded profiles, scripts, and option assignments.

7. Run a Clean Temporary Test Before Editing Multiple Options

Use a controlled sequence so that every result has a clear meaning:

1. Choose one known-good local SDR video.
2. Run mpv with --no-config and gpu-api=auto.
3. Capture a log and record the selected API, context, adapter, and decoder.
4. Test one explicit API while leaving all other options unchanged.
5. If necessary, test one explicit adapter or Vulkan device.
6. Repeat with your normal configuration but no additional command-line overrides.
7. Inspect profiles, includes, bindings, and scripts only if the configured run differs.
8. Add the smallest confirmed fix to the configuration and retest normal media.

After basic playback succeeds, test your actual workflow in stages: subtitles, hardware decoding, HDR, shaders, playlists, network streams, online URLs, IPC clients, and screenshots. Adding features gradually identifies the first component that changes behavior.

Stop when the intended API and device appear in the log and your required playback features operate normally. More overrides are not inherently better. Automatic selection is often the most maintainable configuration when it consistently chooses the correct backend.

8. Quick Fix Checklist

• Reproduce the symptom with a known-good local file.
• Run mpv --no-config --vo=gpu-next --gpu-api=auto.
• Compare explicit opengl, vulkan, and Windows d3d11 tests.
• Use d3d11-adapter=help before selecting a Windows adapter.
• Use vulkan-device=help before selecting a Vulkan device.
• Check mpv.conf, included files, profiles, input bindings, and scripts.
• Test hardware decoding separately with hwdec=no and hwdec=auto-safe.
• On hybrid laptops, verify operating-system or Linux offload routing.
• Capture a verbose log and confirm the selected API and device.
• Change only one option per test and stop after the verified fix.

9. Frequently Asked Questions

9.1 What gpu-api value should I use?

Start with auto. If automatic selection chooses an unsuitable API or fails, compare opengl, vulkan, and d3d11 where supported. Keep the value that initializes cleanly and supports your actual requirements. There is no universal best API for every driver and operating system.

9.2 Why does mpv use the integrated GPU on my laptop?

The operating system, display wiring, launch environment, and graphics driver may route mpv to the integrated GPU. On Windows, configure the graphics preference for the exact mpv executable and verify D3D11 adapter selection. On Linux, test the distribution's supported PRIME offload method or a temporary DRI_PRIME command. Confirm the result in mpv's log rather than relying only on utilization graphs.

9.3 Can gpu-api fix hardware decoding?

Not necessarily. Rendering and decoding are separate stages. If hwdec=no works but hardware decoding fails, the selected output API may already be correct. Investigate the decoder, codec support, bit depth, driver, and copy-back requirements without replacing a working rendering backend.

9.4 Why does mpv work with --no-config?

This result strongly suggests that a configuration option, profile, binding, or script changes playback. Compare logs, search for GPU-related options, and disable individual components temporarily. Do not delete the entire configuration folder before identifying the responsible setting.

9.5 Can yt-dlp or a stream URL select the wrong GPU?

Normally, no. yt-dlp resolves online media and passes streams to mpv, while GPU selection occurs in mpv's video output. Test the resulting media separately when possible. If local playback works, review network, yt-dlp, authentication, format-selection, and stream errors before changing the GPU API.

9.6 How do I know the fix is complete?

The log should show the intended API, context, and graphics device without initialization failures or unexpected fallbacks. Your representative files should play with stable seeking, acceptable dropped-frame behavior, and working subtitles, HDR, shaders, and hardware decoding where required. Once those conditions are met, stop adding overrides and keep a copy of the working settings.