Skip to main content
Hardware decoding offloads video decode work from the CPU to dedicated GPU hardware. mpv does not enable it by default to keep out-of-the-box behavior as reliable as possible, but on modern hardware it usually works well and can reduce CPU usage significantly. 
mpv --hwdec=auto video.mkv
Hardware decoding is disabled by default (--hwdec=no). Enable it at runtime with the Ctrl+h shortcut, which toggles between auto and no.

​
Choosing a method

1

Try auto first

Start with --hwdec=auto. This selects from a whitelist of known-safe hwdec methods that the mpv development team actively supports.
mpv --hwdec=auto video.mkv
2

Test all codecs

To see exactly which hardware decoder is being used and for which codecs:
mpv --hwdec=auto --hwdec-codecs=all -v video.mkv 2>&1 | grep hwdec
3

Add to config if it works

If hardware decoding works as desired for your content, add it to ~/.config/mpv/mpv.conf:
hwdec=auto

​
—hwdec values

mpv --hwdec=<value> video.mkv
ValueDescription
noAlways use software decoding (default)
autoEnable any whitelisted hw decoder
auto-safeAlias for auto
yesAlias for auto
auto-unsafeForcibly enable any hw decoder found (bypasses whitelist — for testing only)
auto-copyLike auto, but only copy-back modes (see below)
auto-copy-safeAlias for auto-copy
auto-copy-unsafeLike auto-copy but without the whitelist
You can also mix specific API names with special values: 
# Try vaapi first, then fall through auto logic
mpv --hwdec=vaapi,auto video.mkv

​
Platform methods

​
vaapi (Intel / AMD)

Requires --vo=gpu, --vo=gpu-next, --vo=vaapi, or --vo=dmabuf-wayland.
mpv --hwdec=vaapi --vo=gpu video.mkv
Works with Intel and AMD GPUs. Requires the OpenGL EGL backend if the GPU does not support DRM modifiers.Requires --vo=gpu or --vo=gpu-next. Available on any platform where CUDA is available.
mpv --hwdec=nvdec --vo=gpu video.mkv
nvdec is the newest and recommended method for NVIDIA GPU hardware decoding. Prefer it over vdpau and cuda.Requires --vo=gpu with --gpu-context=x11, or --vo=vdpau.
mpv --hwdec=vdpau --vo=gpu video.mkv
vdpau always forces RGB conversion in hardware and does not support newer colorspaces (BT.2020) or 10-bit/HDR content correctly. Use --hwdec=nvdec instead.

​
drm (SoC / embedded)

Requires --vo=gpu or --vo=gpu-next with the DRM backend.
mpv --hwdec=drm --vo=gpu video.mkv

​
Native vs. copy modes

Every hardware decoding method comes in two variants:

Native mode (e.g. vaapi)

Decoded frames stay in GPU memory and are passed directly to the video output. Lower overhead, but works only with compatible VOs and may limit which video filters you can apply.

Copy mode (e.g. vaapi-copy)

Decoded frames are copied back to system RAM after decoding. Works with all video filters and all video outputs, at the cost of a copy operation.
# Native: frames stay on GPU (fastest, limited compatibility)
mpv --hwdec=vaapi --vo=gpu video.mkv

# Copy: frames copied back to RAM (compatible with all filters and VOs)
mpv --hwdec=vaapi-copy video.mkv
Use --hwdec=auto-copy to automatically select the best available copy-back method: 
mpv --hwdec=auto-copy video.mkv

​
Hardware decoding + GPU rendering interop

For the best result with native (non-copy) modes, pair --hwdec with --vo=gpu or --vo=gpu-next: 
# NVIDIA on Linux: nvdec + gpu
mpv --hwdec=nvdec --vo=gpu-next video.mkv

# Intel/AMD on Linux: vaapi + gpu-next
mpv --hwdec=vaapi --vo=gpu-next video.mkv

# macOS: videotoolbox + gpu-next
mpv --hwdec=videotoolbox --vo=gpu-next video.mkv

# Windows: d3d11va + gpu with d3d11 context
mpv --hwdec=d3d11va --vo=gpu --gpu-context=d3d11 video.mkv

​
Restricting codecs

By default, hardware decoding is whitelisted for: h264, vc1, hevc, vp8, vp9, av1, prores, prores_raw, ffv1, dpx. Use --hwdec-codecs to override this list: 
# Only use hardware decoding for H.264 and HEVC
mpv --hwdec=auto --hwdec-codecs=h264,hevc video.mkv

# Enable for all codecs
mpv --hwdec=auto --hwdec-codecs=all video.mkv

# Restrict vdpau to H.264 and MPEG-2 only
mpv --hwdec=vdpau --hwdec-codecs=h264,mpeg2video video.mkv

​
When not to use hardware decoding

Disable hardware decoding if you encounter any of the following:
  • Corrupted frames, glitches, or visual artifacts
  • Incorrect colors or discoloration
  • Random crashes or freezes
  • Incorrect playback of HDR content
The first thing to try when debugging playback issues is --hwdec=no.
Known limitations:
  • vdpau: Forces RGB conversion in hardware; BT.2020, 10-bit, and HDR are not supported correctly.
  • dxva2: Always uses BT.601 for RGB conversion; causes incorrect colors on HD/UHD content.
  • cuda: Reported to corrupt timestamps in some mixed streams, causing flashing frames. Prefer nvdec.
  • mediacodec (Android): Forces RGB conversion; 10-bit support is limited and reduces output to 8-bit.

​
Fallback behavior

By default, mpv falls back to software decoding if the hardware decoder fails for 3 consecutive frames (--hwdec-software-fallback=3). You can adjust this: 
# Fall back immediately on any failure
mpv --hwdec=auto --hwdec-software-fallback=1 video.mkv

# Disable fallback (stay in hwdec mode even if frames fail)
mpv --hwdec=auto --hwdec-software-fallback=no video.mkv

​
Additional options

OptionDescription
--hwdec-extra-frames=<N>Number of GPU frames to preallocate for hardware decoding. Increase if you see frame drops during decode.
--hwdec-threads=<N>Number of threads for hardware decoding (default: 4). Set to 0 for auto (number of CPU cores).
--hwdec-image-format=<name>Internal pixel format for hardware decoding (default: no, which uses the decoder’s default).
--gpu-hwdec-interop=<auto|all|no|name>Troubleshooting option to select or block specific hwdec interop backends.
--cuda-decode-device=<auto|0..>Select which GPU to use for cuda/nvdec decoding.
--vaapi-device=<path>DRM device path for vaapi-copy (default: /dev/dri/renderD128).

Build docs developers (and LLMs) love

Get started for freeTalk to us