command-center/omp-docs/tools/niri/displays.md

type, title, description, tags, verified

type	title	description	tags	verified
reference	Display Configuration	Niri output configuration for a multi-monitor desk rig — portrait transforms, position pinning, scale, and iGPU display ownership.	niri display monitors rotation	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

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:

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 — compositor overview and config layout
• tips — reload path and other gotchas
• cachyos — operating system, including wlr-randr