# Complete Hyprland HDR Support Setup Guide

> Master Hyprland HDR support setup with this guide. Enable quirks:prefer_hdr and render:cm_auto_hdr for automatic HDR switching. Get vibrant visuals now.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: how-to-guide
- Published: 2026-07-27

---

**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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/hyprland.conf) to enable HDR globally:

```ini
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`](https://github.com/hyprwm/Hyprland/blob/main/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:

```ini
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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/src/desktop/rule/windowRule/WindowRuleApplicator.cpp). These rules override automatic behavior for specific applications:

**Disable automatic HDR for specific windows:**

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

```

**Force HDR regardless of monitor detection:**

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

```

These rules interact directly with the color-management surface protocol exposed in [`src/protocols/ColorManagement.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/protocols/ColorManagement.cpp), allowing per-window HDR state manipulation.

## Verifying HDR Status

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

```bash
hyprctl monitors | grep HDR

```

This displays the HDR state for each connected monitor, reflecting the internal `inHDR()` status from [`src/output/Monitor.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/output/Monitor.cpp).

## Summary

- **Monitor detection** occurs automatically via EDID parsing in [`src/output/Monitor.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/src/output/Monitor.cpp), the output may appear incorrect or washed out.