Complete Hyprland HDR Support Setup Guide

Hyprland HDR support setup requires enabling the quirks:prefer_hdr configuration option and activating render:cm_auto_hdr for automatic HDR switching based on window content.

Hyprland HDR support setup involves configuring monitor capability detection, color-management protocols, and per-window rendering rules. The compositor automatically detects HDR-capable displays via EDID parsing and provides granular control through configuration values and window rules. This guide covers the technical implementation details and practical configuration steps based on the Hyprland source code.

How Hyprland Detects HDR Monitor Capabilities

When a monitor connects, Hyprland reads the display's EDID to determine HDR capability. In src/output/Monitor.cpp, the compositor populates CMonitor::m_cmType and sets the boolean flag CMonitor::m_supportsHDR based on the EDID metadata.

The monitor class exposes two key methods for HDR state checking:

• supportsHDR() – Returns whether the display hardware supports HDR based on EDID detection.
• inHDR() – Returns whether the monitor is currently operating in HDR mode.

This detection occurs automatically during monitor initialization and requires no user intervention unless you need to override the EDID-based detection.

Configuring HDR Mode in Hyprland

User-control of HDR behavior centers on the quirks:prefer_hdr integer option defined in src/config/values/ConfigValues.cpp. This setting accepts three values:

• 0 – HDR disabled (default SDR mode).
• 1 – HDR enabled for all compatible content.
• 2 – HDR enabled only for Gamescope windows (useful for avoiding HDR in desktop applications while enabling it for games).

Add this to your hyprland.conf to enable HDR globally:

quirks:prefer_hdr=1

Automatic HDR Switching Implementation

For dynamic HDR toggling, Hyprland provides the render:cm_auto_hdr boolean option. When enabled, the compositor monitors window content through the color-management pipeline and automatically switches the display to HDR mode only when HDR content is present.

The auto-HDR logic resides in src/render/Renderer.cpp around line 2300. The renderer queries each surface's color-management state via CColorManagementSurface::isHDR() to determine if the monitor should transition to HDR output. This prevents eye strain from constant HDR usage while ensuring HDR content displays correctly.

Enable automatic switching with:

render:cm_auto_hdr=1

HDR Metadata Creation and Output

When transitioning to HDR mode, Hyprland constructs precise metadata for the display. In src/render/Renderer.cpp around line 2350, the Renderer::createHDRMetadata function builds a hdr_output_metadata structure containing:

• HDR EOTF (Electro-Optical Transfer Function)
• Luminance range (minimum and maximum nits)
• Color primaries (RGB chromaticity coordinates)

The compositor then pushes this metadata to the kernel via pMonitor->m_output->state->setHDRMetadata, ensuring the display receives proper signaling for HDR mode activation.

Color Space Conversion and Tone-Mapping

Hyprland handles mixed SDR/HDR environments through conversion helpers defined in src/render/Renderer.cpp (lines 55-71). The functions isSDR2HDR and isHDR2SDR inspect the transfer functions of source and target SImageDescription objects to determine if color space conversion is required.

When source content exceeds the target display's luminance capabilities, the needsTonemap function triggers tone-mapping. The specific tone-mapping algorithm is retrieved from per-window rules via the tonemap() method, allowing different applications to use different tone-mapping curves.

Window Rules for HDR Control

Fine-grained HDR control is available through window rules implemented in src/desktop/rule/windowRule/WindowRuleApplicator.cpp. These rules override automatic behavior for specific applications:

Disable automatic HDR for specific windows:

windowrule=noautohdr,^(my-gaming-app)$

Force HDR regardless of monitor detection:

windowrule=forcehdr,^(my-video-player)$

These rules interact directly with the color-management surface protocol exposed in src/protocols/ColorManagement.cpp, allowing per-window HDR state manipulation.

Verifying HDR Status

Confirm your current HDR configuration using Hyprland's runtime control utility:

hyprctl monitors | grep HDR

This displays the HDR state for each connected monitor, reflecting the internal inHDR() status from src/output/Monitor.cpp.

Summary

• Monitor detection occurs automatically via EDID parsing in src/output/Monitor.cpp, setting CMonitor::m_supportsHDR based on display capabilities.
• Global HDR activation requires setting quirks:prefer_hdr=1 in your configuration.
• Automatic switching is controlled by render:cm_auto_hdr, which checks CColorManagementSurface::isHDR() to toggle HDR mode dynamically.
• Metadata generation happens through Renderer::createHDRMetadata in src/render/Renderer.cpp, populating the hdr_output_metadata structure with EOTF and luminance data.
• Color conversion uses isSDR2HDR and isHDR2SDR helpers, with needsTonemap applying per-window tone-mapping rules.
• Per-window control is available via noautohdr and forcehdr window rules.

Frequently Asked Questions

Does Hyprland support HDR out of the box?

Hyprland includes HDR infrastructure in the source code, but you must explicitly enable it. The compositor detects HDR-capable displays automatically via EDID, but the quirks:prefer_hdr option defaults to disabled (0). Set it to 1 in your configuration to activate HDR support.

How do I check if my monitor supports HDR in Hyprland?

Run hyprctl monitors | grep HDR in your terminal. This queries the runtime state of CMonitor::m_supportsHDR and inHDR() from src/output/Monitor.cpp. If your monitor reports HDR capability via EDID but shows as disabled, you may need to enable quirks:prefer_hdr.

What is the difference between quirks:prefer_hdr values?

The quirks:prefer_hdr integer in src/config/values/ConfigValues.cpp accepts three values: 0 completely disables HDR rendering, 1 enables HDR for all compatible applications, and 2 restricts HDR activation to Gamescope windows only. Value 2 is useful for users who want HDR in games but prefer SDR for desktop applications to avoid color shifts.

Can I force HDR for specific applications regardless of monitor capability?

Yes. Use the windowrule=forcehdr,^(application-class)$ rule in your configuration. This overrides automatic detection and forces the color-management surface into HDR mode. However, if your display does not support HDR according to EDID detection in src/output/Monitor.cpp, the output may appear incorrect or washed out.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}