---
type: reference
title: Display Configuration
description: Niri output configuration for a multi-monitor desk rig — portrait transforms, position pinning, scale, and iGPU display ownership.
tags:
  - niri
  - display
  - monitors
  - rotation
verified: 2026-08-28
---

# Display Configuration

How a multi-monitor desk rig is configured in niri: portrait external panels
flanking a laptop panel, positions pinned by hand, and the integrated GPU kept
as the display owner.

**Config:** `~/.config/niri/cfg/display.kdl`
**Probe:** `wlr-randr` (installed by CachyOS) reports what the compositor
actually committed — connectors, preferred modes, transforms, scale, positions.

---

## The rig

Three outputs in a row: two external monitors rotated to portrait, one
internal laptop panel in landscape at the right.

```
┌──────────────┬──────────────┬──────────────┐
│              │              │              │
│   DP-1       │     DP-3     │    eDP-1     │
│  external    │   external   │    internal  │
│  1920x1200   │   1920x1200  │   2560x1600  │
│  Portrait    │  Portrait    │   Landscape  │
│  90° rotate  │  270° rotate │   1.5x scale │
│              │              │              │
└──────────────┴──────────────┴──────────────┘
     x=0,0          x=1200,0       auto-placed
```

| Output | Role | Transform | Position | Scale |
|--------|------|-----------|----------|-------|
| `DP-1` | External, left | `90` (portrait) | `x=0 y=0` | 1.0 |
| `DP-3` | External, center | `270` (portrait) | `x=1200 y=0` | 1.0 |
| `eDP-1` | Internal panel | none (landscape) | auto-placed | 1.5 |

The two portrait panels are 1200 px wide after rotation, which is why the
second one starts at `x=1200`. The internal panel declares no position at
all — niri auto-places it to the right of the explicitly positioned outputs.
That is the only reliable way to keep a third panel from landing on top of
the rig when a cable is re-seated.

---

## The config pattern

```kdl
output "DP-1" {
    transform "90"
    position x=0 y=0
}

output "DP-3" {
    transform "270"
    position x=1200 y=0
}

output "eDP-1" {
    // no position — auto-placed to the right of the DP-* outputs
    scale 1.5
}
```

Three rules learned the hard way:

1. **One output, one block.** A second block keyed by the make/model string
   (`output "Samsung Electric Company …"`) that also sets `transform` fights
   the connector-keyed block. Use the make/model form only to pin a `mode`
   for an output whose connector name is unstable across boots, and never
   set a transform in both places.
2. **Positions are absolute, not relational.** Niri does not reflow the rig
   when one panel is disconnected — a missing output leaves a hole at its
   coordinates. Verify with `wlr-randr` after any cable or dock change.
3. **Re-assert rotation after a config reload, then confirm.** A transform
   silently reverting to landscape is the usual symptom of a duplicate
   output block, not of a failed reload.

Modes must match what the panel reports. Check `wlr-randr` for the preferred
mode before writing a `mode` line; a `mode` the panel cannot drive leaves the
output dark or drops it.

---

## GPU assignment

The integrated GPU drives all display output; the discrete GPU is available
for compute but must not take the outputs. Pin the render node explicitly in
`~/.config/niri/cfg/misc.kdl`:

```kdl
environment {
    render-node "/dev/dri/renderD129"
}
```

Without the pin, the session's render node follows probe order and can land
on the discrete GPU — which costs display-linked copies and, on hybrid
graphics laptops, is a common trigger of the suspend/resume deadlock covered
in the sleep-wake investigation report.

---

## Reload

`niri msg action load-config-file` reloads live. Never `SIGHUP` the process
— see [[tips]].

---

## See Also

- [Niri](/tools/niri/index.md) — compositor overview and config layout
- [[tips|tips]] — reload path and other gotchas
- [[cachyos|cachyos]] — operating system, including `wlr-randr`