“There’s no software to manage my displays,” he said. The software was installed. It just couldn’t arrange anything — and neither could the four things we tried to install.

The Situation

Two panels: a 1920x1200 desktop monitor on DisplayPort and a 1920x1080 portable touch panel on HDMI. A fresh Omarchy install, Hyprland 0.56, and a very simple request: make the big one the main screen, the touch panel the second one, and stop the touch panel from doing things on both screens at once.

The first survey said the desktop had no display management at all. nwg-displays, wdisplays, arandr — none of them installed. The obvious read was “install a display arranger.”

That was the wrong turn, and it cost more time than any of the actual bugs.

Act I: The Panel That Exists and Cannot Arrange

Omarchy ships a Display panel. Nobody had told him. SUPER + CTRL + D opens it, and it does brightness, text size, six scale presets and an enable/disable row per monitor.

What it does not do is position anything. No layout canvas, no resolution picker, no rotation. So “there’s no software” was accurate in spirit and wrong in fact. The panel exists to make one monitor readable, not two monitors coherent.

Meanwhile the shell reported both panels already side by side, both at scale 1, which is why the complaint sounded like a driver problem and not a layout problem.

Act II: The Parser Ate Every Tutorial

Here is the line that reframes the entire afternoon:

$ hyprctl keyword monitor "HDMI-A-1,1920x1080@60,0x0,1"
keyword can't work with non-legacy parsers. Use eval.

Hyprland 0.55 moved its configuration from hyprlang to Lua. hyprctl keyword — the call that every display tutorial, wiki snippet and GUI arranger on the internet uses to make a live change — is dead on this parser. It does not warn. It does not fail loudly. It prints that one line and returns success, which is the worst possible behaviour: any tool that shells out to keyword monitor will cheerfully report “applied” having done absolutely nothing.

That is the real answer to “no software manages my displays.” You could install every arranger in the AUR and they would all push strings into a door that has been welded shut.

Live changes go through Lua now:

hyprctl eval 'hl.monitor({ output = "DP-2", mode = "1920x1200@59.95", position = "0x0", scale = 1 })'

hl.monitor takes output, mode, position, scale, disabled, transform, mirror, bitdepth, cm, vrr and reserved_area. Multiple statements in a single eval string apply together, so a whole layout can move in one call.

The dispatch surface moved with it. The classic dispatcher syntax fails in a way that reads like a syntax error rather than a deprecation:

$ hyprctl dispatch focusmonitor DP-2
error: [string "return hl.dispatch(focusmonitor DP-2)"]:1: ')' expected near 'DP'

The replacement is hl.dispatch(hl.dsp.focus({ monitor = "DP-2" })), with siblings like hl.dsp.workspace.move({ monitor = "DP-2" }) and hl.dsp.window.move({ workspace = "3" }).

Act III: The Touch Panel Doing Things on Both Screens

Separate bug, separate subsystem. Tapping the portable panel moved the cursor or clicked things on the desktop monitor too. Not a driver fault and not a calibration fault. The panel’s digitizer had no output bound to it:

$ hyprctl getoption input:touchdevice:output
str: [[Auto]]
set: false

Auto means the absolute digitizer coordinates get stretched across the entire virtual desktop. The panel is one third of the total width, so a tap at its right edge landed on the other screen. Physically correct, conceptually wrong.

hyprctl eval 'hl.config({ input = { touchdevice = { output = "HDMI-A-1" } } })'
hyprctl eval 'hl.device({ name = "<stylus-device>", output = "HDMI-A-1" })'
hyprctl getoption input:touchdevice:output     # str: HDMI-A-1 / set: true

Two details worth carrying forward. The stylus is a separate device from the touch panel and needs its own binding, or pen input keeps spanning both screens. And hyprctl devices -j will not confirm any of this for you: the .touch[] entries carry an address and a name, no output field at all. getoption is the verification, and it only reflects the global setting.

If you rotate the panel, rotate the digitizer with it. input.touchdevice.transform takes the same 0-7 values as the monitor transform, and a mismatch gives you a touchscreen where taps land mirrored. We wired that into the same command that rotates the display so they cannot drift apart.

Act IV: “It’s Still Flipped”

By now the monitors were in the right places. The desktop monitor sat at 0x0, the touch panel to its right. And SUPER+1 still focused the touch panel.

Because monitors and workspaces are two different bindings:

$ hyprctl workspaces -j
ws 1 -> HDMI-A-1
ws 2 -> DP-2

Workspace 1 was on the touch panel while the desktop monitor sat at the origin. Hyprland assigns workspaces to outputs by connection order, not by layout position. Moving a monitor does not move its workspaces. Every tutorial that says “just set the position” is describing half the system.

hl.workspace_rule({ workspace = "1", monitor = "DP-2", default = true })

hyprctl reload applies workspace rules to new workspaces only. Anything already alive keeps its monitor and has to be moved by focusing it and then hl.dsp.workspace.move({ monitor = "DP-2" }).

We verified it the way a user feels it. Focus the wrong monitor, trigger what SUPER+1 triggers, check which monitor ended up focused. It flipped.

Act V: Do Not Trust A Fast Read

One scare worth recording. Immediately after applying a monitor mode, the JSON reported the panel’s width and height as null:

{"name":"HDMI-A-1","x":0,"y":0,"w":null,"h":null}

Which looks exactly like a destroyed display mode. A quarter of a second later, the same query returned 1920x1080@60 and everything was fine. The compositor applies changes asynchronously, so a read that follows eval by zero milliseconds returns stale or half-written state.

Add a short sleep before reading, or you will spend ten minutes debugging a change that already succeeded.

Receipts

# survey
hyprctl monitors all            # every output, including disabled
hyprctl monitors all -j         # JSON: modes, scale, transform, mirrorOf, disabled

# live layout (the only working path on the Lua parser)
hyprctl eval 'hl.monitor({ output = "DP-2", mode = "1920x1200@59.95", position = "0x0", scale = 1 })'

# touch panel + stylus
hyprctl eval 'hl.config({ input = { touchdevice = { output = "HDMI-A-1" } } })'
hyprctl eval 'hl.device({ name = "<stylus-device>", output = "HDMI-A-1" })'

# workspace ownership
hyprctl eval 'hl.workspace_rule({ workspace = "1", monitor = "DP-2", default = true })'
hyprctl eval 'hl.dispatch(hl.dsp.focus({ workspace = "1" }))'

Two mapping traps that cost us real time: hyprctl clients -j reports .monitor as a numeric id, not a connector name, so "1" in that field is not monitor DP-1. And a disabled output reports width: 0, so re-enabling it needs a mode from availableModes, not the current one.

Takeaway

Three things bind to a display, and they live in three different vocabularies:

  • Layout — hl.monitor(): where the panel sits, its mode, its scale, its rotation.
  • Input — input.touchdevice.output and .transform: which panel the digitizer belongs to, and in which orientation.
  • Workspace ownership — hl.workspace_rule(): which portion of your keyboard shortcuts lands where.

Fix one and the others stay wrong, which is why “the display is flipped” can survive three correct repairs. And before any of it, check how your compositor wants to be spoken to. If hyprctl keyword returns keyword can't work with non-legacy parsers, no amount of package installation will help you.

The whole thing is now a small script: displays status, swap, row, stack, mirror, rotate, touch, save — with save writing explicit monitor rules plus a marker-delimited touch block so a reboot restores the layout instead of guessing.

The lesson is not “Omarchy can’t do monitors.” It is that the interface moved and the documentation ecosystem has not caught up, so the error message is the only honest documentation you will get.