mpv NVDEC Not Working: How to Fix It

When mpv NVDEC is not working, the player usually falls back to software decoding, rejects the selected hardware decoder, or fails to open the video altogether. The most common causes are an unsupported codec or pixel format, an NVIDIA driver problem, an overridden configuration option, an incompatible output path, or mpv running on the wrong GPU in a hybrid system. Start with a clean command that isolates decoding from scripts, profiles, shaders, subtitles, and other customizations. Once that test works, restore your normal setup one component at a time and stop as soon as you find the option that changes the result.

1. Confirm the Symptom With a Minimal Clean mpv Command

Do not begin by editing your main configuration or installing codec packs. First determine whether NVDEC fails in mpv itself or only within your customized setup. Open PowerShell, Command Prompt, Terminal, or a Linux shell and run mpv with configuration loading disabled.

mpv --no-config --hwdec=nvdec "path-to-video-file"

Replace the placeholder with a local video file that you know plays correctly in software. Quote the path if it contains spaces. On Windows, you can drag a file into PowerShell or Command Prompt to insert its path, although shell quoting rules still apply.

Watch the terminal output while the video opens. A successful test normally includes a line indicating that hardware decoding is being used, with NVDEC named as the decoder. Playback should begin normally, and CPU use will often be lower than with software decoding. GPU monitoring tools may also show video-decoder activity, but terminal output is the more direct first check.

If the test fails, compare it with automatic hardware-decoder selection:

mpv --no-config --hwdec=auto "path-to-video-file"

If auto selects another hardware API, that does not prove NVDEC is broken. It means mpv found a different usable path. If both commands fall back to software, investigate the driver, codec, GPU selection, and mpv build before changing normal configuration options.

1.1 Compare nvdec With nvdec-copy

mpv supports two relevant NVDEC modes. The nvdec mode aims to keep decoded frames in GPU-accessible memory, reducing unnecessary transfers. The nvdec-copy mode decodes on the NVIDIA GPU and then copies frames back to system memory. Copy mode is less efficient, but it can work around interoperability problems between the decoder and video output stack.

mpv --no-config --hwdec=nvdec-copy "path-to-video-file"

If nvdec-copy works while nvdec fails, the NVIDIA decoder and codec are probably functional. The likely problem is zero-copy frame sharing with the selected GPU context, output backend, display server, or hybrid-GPU arrangement. In that situation, keeping hwdec=nvdec-copy is a reasonable practical fix, especially if playback is smooth and GPU decoding is confirmed.

Stop changing settings if the clean command succeeds and performance is acceptable. You have already narrowed the problem to your normal configuration or launch environment.

2. Check Options That Can Disable or Disrupt NVDEC

If the clean test succeeds but ordinary playback does not, inspect the options loaded during normal startup. mpv can read a main configuration file, file-specific options, profiles, scripts, and command-line arguments. Later options can override earlier ones, so a valid hwdec=nvdec line does not guarantee it remains active.

2.1 Inspect mpv.conf and profiles

Search your configuration files for hwdec, vo, gpu-api, gpu-context, profile, vf, and video-sync. Pay particular attention to lines such as:

hwdec=no
hwdec=auto
hwdec=nvdec-copy
vo=gpu
vo=gpu-next
gpu-api=vulkan
gpu-api=opengl
gpu-context=d3d11

None of these lines is automatically wrong. The issue is whether a global option or automatically selected profile replaces the NVDEC setting you intended to use. Temporarily comment out only the suspected line rather than deleting the entire configuration folder.

To inspect a named profile, run:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the profile name from your configuration. Look for conditional profiles that activate for fullscreen playback, particular protocols, codecs, resolutions, HDR files, or display names. Success means normal playback reports NVDEC after the conflicting option is removed or corrected. At that point, stop editing unrelated settings.

2.2 Check input bindings and scripts

An input binding can change hardware decoding while mpv is running. Search input.conf for commands involving hwdec, set, cycle-values, profiles, or video filters. A binding that cycles hardware decoding may leave it disabled without making the change obvious.

Scripts can also add filters, switch profiles, alter the video output, or restart playback with different properties. Test without configuration to exclude all normal scripts, then temporarily disable only the suspected script or move it out of the script-loading path. Do not erase your entire setup.

Subtitles and audio tracks do not normally determine whether NVDEC can decode the video track. However, scripts that process subtitles, audio visualizers, or subtitle-oriented shaders may alter the rendering chain. Use the track list to confirm that a genuine video track is selected and that an attached picture or visualizer is not being mistaken for the main video.

2.3 Test filters, shaders, HDR settings, and screenshots

Some video filters require frames in system memory and can force a hardware-decoding fallback or trigger a copy path. Test without custom filters and shaders:

mpv --no-config --hwdec=nvdec --vf-clr --glsl-shaders-clr "path-to-video-file"

HDR tone mapping, interpolation, debanding, scaling shaders, and screenshot options are generally rendering features rather than decoder selections. They can still expose backend incompatibilities or increase GPU load. If NVDEC works without them, reintroduce one feature at a time.

A screenshot failure alone does not mean NVDEC failed. Hardware-decoded frames may require a different transfer or screenshot path. Confirm the active decoder separately in logs or the stats overlay before treating a screenshot problem as a decoding problem.

2.4 Understand Vulkan, OpenGL, and D3D11 interactions

NVDEC performs decoding, while Vulkan, OpenGL, and D3D11 are involved in rendering and presentation. They are separate stages, but they must exchange frames successfully for a zero-copy path to work.

• nvdec may fail when decoded frames cannot be shared with the selected GPU API or context.
• nvdec-copy can work because it transfers frames through system memory instead of requiring the same interoperability path.
• On Windows, D3D11-related presentation choices and GPU assignment can affect which adapter receives frames.
• On Linux, Vulkan or OpenGL behavior can differ between X11 and Wayland sessions, especially on hybrid systems.

Test one backend at a time rather than combining many changes:

mpv --no-config --hwdec=nvdec --vo=gpu-next --gpu-api=vulkan "path-to-video-file"
mpv --no-config --hwdec=nvdec --vo=gpu-next --gpu-api=opengl "path-to-video-file"

If your mpv build does not support a specified option or backend, it will report that in the terminal. Do not copy backend settings permanently merely because they appear in somebody else's configuration. Keep the combination that works with your operating system, driver, and mpv build.

3. Verify NVIDIA Driver and Codec Support

NVDEC requires a supported NVIDIA GPU, a functioning proprietary NVIDIA driver where applicable, and media encoded in a format the GPU can decode. mpv cannot add hardware capabilities that the GPU lacks.

3.1 Confirm that the NVIDIA driver is active

On Windows, verify that the NVIDIA adapter appears without an error in Device Manager and that the NVIDIA driver is installed. On Linux, run:

nvidia-smi

If the command cannot communicate with the driver, fix the driver installation before troubleshooting mpv. A system can display a desktop using an integrated GPU or fallback driver even when the NVIDIA driver required by NVDEC is unavailable.

Use official operating-system repositories or NVIDIA's official driver channels. Avoid codec packs and random binary downloads. Codec packs do not repair NVDEC driver support and can introduce unrelated conflicts.

On modern macOS systems, NVIDIA NVDEC is generally not a viable mpv decoding route because current macOS releases do not provide the required contemporary NVIDIA driver stack. Use the hardware-decoding API available to the platform, commonly VideoToolbox, rather than forcing nvdec. Older Mac and macOS combinations vary, but their capabilities depend on the installed NVIDIA hardware and driver support.

3.2 Check the NVIDIA codec support matrix

Hardware-decoding support varies by GPU generation and codec profile. A GPU may decode H.264 but not HEVC, or decode 8-bit HEVC but not a particular 10-bit or 4:4:4 profile. AV1 decoding is available only on supported generations. Resolution, chroma format, bit depth, and codec level can also matter.

Test several known local files. If H.264 uses NVDEC but a specific HEVC, VP9, or AV1 file does not, mpv is probably behaving correctly for the available hardware. Compare the exact GPU model and media format with NVIDIA's official Video Encode and Decode GPU Support Matrix.

Software fallback is not necessarily an error. It is the expected result when the hardware cannot decode the stream. Stop searching for an mpv NVDEC not working fix if only unsupported formats fall back and supported samples use NVDEC successfully.

3.3 Account for hybrid GPU laptops

Hybrid laptops often contain an integrated GPU connected to the display and a discrete NVIDIA GPU used on demand. mpv may launch on the integrated adapter while NVDEC initializes on the NVIDIA adapter, creating a frame-sharing problem.

On Windows, assign mpv to the high-performance NVIDIA GPU through Windows Graphics settings or the NVIDIA application settings. On Linux, launch mpv using the distribution's supported PRIME render-offload method. Environment variables and commands differ by distribution and driver packaging, so follow the documentation for your installation rather than pasting an unverified command.

After changing GPU assignment, repeat the minimal test. Success means NVDEC appears in the terminal and playback works without an interop error. If only nvdec-copy works, it remains a valid workaround for a cross-GPU presentation path.

4. Separate Local Decoding From Stream and External-Tool Problems

NVDEC receives compressed video after mpv has opened or downloaded the media. It cannot fix an inaccessible URL, expired stream token, unsupported manifest, authentication failure, or missing external downloader.

4.1 Test a local file before an online URL

If local files use NVDEC but an online URL does not open, the decoder is probably not the cause. Test the URL without custom configuration and inspect the terminal for network, TLS, yt-dlp, or format-selection errors.

mpv --no-config --hwdec=nvdec "https://example.com/media-url"

For websites supported through yt-dlp, make sure mpv can find an up-to-date, trusted installation of yt-dlp. Do not download renamed executables from unofficial mirrors. A missing yt-dlp executable prevents URL resolution before NVDEC is involved.

Network streams can also change codec or format based on availability. A local H.264 file may use NVDEC while a selected AV1 web format falls back because the GPU lacks AV1 support. Inspect the selected video track and codec rather than assuming all versions of a stream are equivalent.

4.2 Rule out damaged or unusual media

Try another file encoded with a common supported format. Corrupt packets, malformed containers, unusual profiles, or incomplete downloads may prevent hardware decoding even when software decoding can conceal some errors. If only one file fails, inspect that file rather than changing global mpv settings.

Audio backend failures can stop playback or make the player appear broken, but they do not establish that NVDEC failed. As a diagnostic step, test video without audio:

mpv --no-config --no-audio --hwdec=nvdec "path-to-video-file"

If this works, troubleshoot the audio device or backend separately. Likewise, a subtitle parsing error should be isolated with --no-sub. These tests are relevant only when terminal output points to audio or subtitle initialization rather than video decoding.

5. Use Logs and Runtime Information to Identify the Active Decoder

Visual smoothness is not proof of hardware decoding. A fast CPU may decode the file easily in software. Use mpv's terminal output, logs, and runtime statistics to verify the decoder.

5.1 Increase decoder and video-output logging

Run a clean test with focused logging:

mpv --no-config --hwdec=nvdec --msg-level=vd=trace,vo=debug --log-file=mpv-nvdec.log "path-to-video-file"

Search the resulting log for nvdec, hwdec, fallback, cuda, vulkan, opengl, d3d11, and failed. The important distinction is between a decoder initialization failure, an unsupported media format, and a frame-interop failure after decoding begins.

If the log says the codec or format is unsupported by the hardware, use software decoding or another supported hardware API. If NVDEC initializes but the video output cannot accept its frames, test nvdec-copy or another rendering backend.

5.2 Check the stats overlay and track list

During playback, mpv's built-in stats overlay can display decoder, frame, timing, and rendering information. The default i binding commonly opens statistics, although custom input files can replace that binding. Look for hardware-decoding or decoder information naming NVDEC.

The track list also confirms which video stream is active. This matters for files with multiple video tracks, attached cover images, alternate codecs, or online formats. Verify that the selected track is the one whose codec you expect the GPU to support.

Success is explicit: the terminal, log, or stats display identifies NVDEC as active. Once you have that confirmation and playback is stable, stop changing unrelated subtitle, audio, IPC, playlist, or screenshot options.

6. Run a Clean Temporary Test Before Permanent Changes

Use a controlled sequence so that each result tells you something useful:

1. Test a known local H.264 file with --no-config --hwdec=nvdec.
2. If it fails, try the same file with --hwdec=nvdec-copy.
3. If both fail, confirm the NVIDIA driver and GPU codec support.
4. If copy mode works, test OpenGL and Vulkan separately or retain copy mode.
5. If the clean test works, launch normally and inspect profiles, scripts, filters, and bindings.
6. Restore custom shaders, HDR processing, subtitles, scripts, and URL handling one item at a time.

Do not change the driver, mpv build, rendering API, configuration, scripts, and media file simultaneously. That makes success impossible to attribute to a specific fix. Keep notes of the exact commands and outcomes, especially on systems with multiple GPUs.

Only after a clean test succeeds should you add a persistent line such as the following to mpv.conf:

hwdec=nvdec

If only copy mode is reliable, use:

hwdec=nvdec-copy

Automatic selection is also appropriate when you use mpv across different computers or GPUs:

hwdec=auto

7. Quick Fix Checklist

• Run mpv --no-config --hwdec=nvdec "file" with a known supported local file.
• Confirm the terminal or stats overlay explicitly names NVDEC.
• Try nvdec-copy to diagnose zero-copy or GPU interop problems.
• Verify the NVIDIA driver is loaded and the intended GPU is active.
• Check the exact codec, bit depth, chroma format, and GPU support matrix.
• Search configuration files and profiles for overriding hwdec options.
• Temporarily remove relevant filters, shaders, and suspect scripts.
• Test Vulkan and OpenGL separately rather than changing multiple options.
• Assign mpv to the NVIDIA GPU on a hybrid laptop.
• Separate URL or yt-dlp failures from actual video-decoder failures.
• Create a focused log with --msg-level and --log-file.
• Stop when NVDEC is confirmed and playback is stable.

8. Frequently Asked Questions

8.1 How do I know whether mpv is actually using NVDEC?

Read the startup output or open the stats overlay during playback. Look for a message that explicitly identifies NVDEC or hardware decoding. CPU usage alone is not reliable evidence because software decoding performance varies.

8.2 What is the difference between nvdec and nvdec-copy?

nvdec seeks an efficient GPU-oriented path for decoded frames. nvdec-copy copies decoded frames into system memory before rendering. Copy mode can consume more bandwidth but often avoids backend, display-server, and hybrid-GPU interoperability failures.

8.3 Why does NVDEC work for H.264 but not HEVC, VP9, or AV1?

Codec support depends on the NVIDIA GPU generation and the stream's profile, resolution, bit depth, and chroma format. Check the exact media properties against NVIDIA's support matrix. Unsupported streams should be decoded in software or through another available hardware API.

8.4 Can subtitles or audio disable NVDEC?

Ordinary subtitles and audio tracks usually do not disable NVDEC. Custom scripts, visualizers, filters, or complex rendering chains associated with them can alter playback behavior. Test with --no-sub or --no-audio only when logs suggest those subsystems are preventing playback.

8.5 Why does NVDEC fail only for online videos?

The website may provide a codec your GPU cannot decode, or mpv may be failing before decoding because yt-dlp cannot resolve the URL. Confirm that a local supported file uses NVDEC, then inspect the selected online format and any yt-dlp or network errors.

8.6 Should I reinstall mpv or delete its configuration?

Not initially. A --no-config test provides the same isolation without destroying a working setup. Reinstall only when logs indicate missing build capabilities or damaged program files, and preserve your configuration so you can restore components gradually.