Enable HDR in mpv on Wayland: Config, Checks, Fixes

You switched on HDR in your desktop settings, opened a 4K HDR file in mpv, and the picture looks gray or oddly dark. Usually one link in the chain is missing: the mpv build, the compositor, the graphics driver, or the monitor mode. This guide walks through each link, gives you a small config you can switch on and off, and shows how to tell HDR output from a quiet tone-map to SDR.

One caveat first. Phoronix reported that MPV 0.42 brings Wayland improvements and improved HDR, but the retrieved page text doesn't say which options changed. Read the official mpv release notes and the manual for your installed version before trusting any option name below.

Every command and config in this guide is untested. Nobody has run it and recorded the output for this article. The expected results describe what to look for, not captured output.

Step 0: Know what you need

HDR passthrough on Wayland needs four things to line up. mpv has to be recent enough to tell the compositor about HDR, and the compositor has to accept that signal. The driver stack has to expose it, and the monitor has to be in an HDR mode.

If any one is missing, mpv falls back to tone-mapping the video to SDR. That's why you get a normal, slightly flat picture instead of an error.

The compositor matters most. KDE Plasma and GNOME each document their own HDR support, and wlroots-based compositors vary a lot by project. Check your compositor's documentation for a current statement on HDR rather than assuming.

This next point is an inference from how the pieces fit together, not a claim from a source: if the compositor has no HDR toggle, mpv has nowhere to send HDR.

Step 1: Run the prerequisites checklist

1. Check the mpv version. Run mpv --version. Expect a first line like "mpv 0.4x.x" plus the libplacebo and FFmpeg versions. Compare the number against the release notes to see whether your build has the Wayland and HDR changes. Distro and Flatpak builds can lag well behind upstream. (Untested.)
2. Confirm you are in a Wayland session. Run echo $XDG_SESSION_TYPE. Expect wayland. If you see x11, log out and pick the Wayland session at the login screen. (Untested.)
3. Identify the compositor. Run echo $XDG_CURRENT_DESKTOP. Expect something like KDE or GNOME. On wlroots compositors the variable may be empty or set to the compositor name. (Untested.)
4. Check for a color-management protocol. If wayland-info is installed (usually in a package called wayland-utils), run wayland-info | grep -i color. Expect lines naming a color-management or HDR-related interface if the compositor offers one. Nothing printed suggests the compositor lacks it, but the exact protocol names depend on your compositor version, so confirm in its docs. (Untested.)
5. Check Vulkan. Run vulkaninfo --summary. Expect your GPU listed with a driver name. If it errors out, the Vulkan-based mpv options below won't work. (Untested.)
6. Ask mpv what it supports. Run mpv --gpu-context=help and look for a Wayland Vulkan entry. Then run mpv --list-options | grep -i colorspace-hint to see whether the HDR signaling option exists in your build. (Untested.)
7. Enable HDR in the compositor. In KDE Plasma, the display settings have an HDR option for capable monitors. In GNOME and wlroots compositors, look in the display settings or the compositor's config documentation. Option names and availability change between versions, so verify them in the documentation for yours. Also check that the monitor isn't stuck in an SDR-only mode or on a cable or port that limits bandwidth.

Step 2: Back up your config and try options without saving them

Before editing anything, copy your current file. Run cp ~/.config/mpv/mpv.conf ~/.config/mpv/mpv.conf.bak. If you have no mpv.conf yet, skip the copy and delete the new file later to revert. (Untested.)

Next, test on the command line so nothing is permanent:

mpv --vo=gpu-next --gpu-context=waylandvk --target-colorspace-hint=yes /path/to/hdr-video.mkv

This is untested, and the option names come from general mpv knowledge, not from the release notes. Run man mpv or check the manual for your version to confirm each one exists. If the video plays and looks right, move on. If not, jump to the table at the end. For more on this, see more on gimp flatpak vs snap vs appimage: which updates fastest?.

Step 3: Save a minimal config as a profile

A profile keeps HDR settings away from your normal SDR playback. Add this to ~/.config/mpv/mpv.conf:

[wayland-hdr]
vo=gpu-next
gpu-context=waylandvk
target-colorspace-hint=yes

Then launch with mpv --profile=wayland-hdr file.mkv. (Untested.)

The config is deliberately short. Skip overrides like forced transfer or primaries values until the basic setup works, because wrong overrides are a common cause of washed-out output. Once you trust the profile, you can move the lines to the top of the file so they apply everywhere.

To revert, run mv ~/.config/mpv/mpv.conf.bak ~/.config/mpv/mpv.conf, or delete the [wayland-hdr] block. (Untested.)

Step 4: Verify HDR is really active

A good-looking picture proves nothing, because tone-mapped SDR can look fine. Use these checks:

1. Play an HDR file (look for BT.2020 and PQ or HLG in the file info) and press i to open mpv's stats overlay. Check the video's reported colorspace and transfer function. Page names and fields vary by version.
2. Launch with --msg-level=all=v or --msg-level=vo=v and read the terminal output for lines about the output colorspace or HDR metadata. Expect a mention of PQ or BT.2020 on the display side if the signal is passed through. (Untested.)
3. Toggle HDR off in the compositor and replay the same clip. If the picture changes noticeably, such as brightness, highlight detail or saturation, mpv was probably sending HDR before. This is an inference, not a documented test.

If the stats show an SDR output while the source is HDR, mpv is tone-mapping. Go back to the prerequisites.

Troubleshooting

| Symptom | Likely cause | What to try | |---|---|---| | Washed-out, gray colors | HDR signal reaching an SDR desktop, or the compositor not told about HDR | Turn on HDR in the compositor, or remove target-colorspace-hint and let mpv tone-map to SDR. Remove any manual target-trc or target-prim overrides. | | Too dark | Tone-mapping to a low peak, or the compositor's SDR brightness setting is low | Raise brightness in the display settings and check the compositor's HDR brightness options. Test with a different clip. | | Black screen | Vulkan context failing on your driver or session | Run vulkaninfo --summary. Try --gpu-context=wayland with --vo=gpu-next, or fall back to --vo=gpu. Update Mesa or the proprietary driver. | | HDR not detected | Old mpv build, X11 session, or compositor lacking HDR support | Recheck steps 1 to 3 of the checklist. Try a newer mpv build. Flatpak or distro packages can lag. | | Option rejected at startup | Option name or value does not exist in your version | Run mpv --list-options and read the manual for your build. |

Also read: wine wow64 mode explained: should you switch prefixes?: the details

If a change makes things worse, restore the backup first, then reintroduce options one at a time. That isolates the culprit faster than guessing.

What to expect next

Wayland HDR support is moving fast, so a config that fails today may work after a compositor or Mesa update. When you upgrade, reread the mpv release notes and your compositor's HDR documentation before changing anything. Keep the [wayland-hdr] profile around, and rerun the verification step after each upgrade.