Monitor layout lost after Quattro: monitors.conf replaced by monitors.lua

You upgraded to Omarchy 4 and your screens came back in the wrong order, the wrong rotation, or at the wrong scale. Your old ~/.config/hypr/monitors.conf is still sitting there. Omarchy 4 never reads it.

The fix

Checked on 4.0.4. The same steps apply to every 4.0.x release, because nothing in 4.0.1 through 4.0.4 changed this.

1. Look at what you had. cat ~/.config/hypr/monitors.conf. The file survives the upgrade unchanged, so your old layout is still readable. The upgrade makes no backup of it, so if it is gone, something other than Omarchy removed it.

2. Open the new file. Use Setup > Monitors in the Omarchy menu, or run omarchy launch config-editor ~/.config/hypr/monitors.lua.

3. Translate each line. The Lua form takes one table per output:

   -- monitor=,preferred,auto,auto
   hl.monitor({ output = "", mode = "preferred", position = "auto", scale = "auto" })
   
   -- monitor = DP-2, 2560x1440@165, 1920x0, 1
   hl.monitor({ output = "DP-2", mode = "2560x1440@165", position = "1920x0", scale = 1 })
   
   -- monitor = DP-2, preferred, auto, 1, transform, 1
   hl.monitor({ output = "DP-2", mode = "preferred", position = "auto", scale = 1, transform = 1 })
   
   -- monitor=DP-2,disable
   hl.monitor({ output = "DP-2", disabled = true })

   Positional arguments become named keys. Extra 3.x flags that used to trail the line, such as transform and vrr, become keys in the same table. Numbers stay unquoted, strings get quotes, and scale = "auto" is a quoted string because it is not a number. mirror = "eDP-1" is the mirroring key, which is what omarchy-hyprland-monitor-internal-mirror writes.

4. Match monitors by description if you have identical panels. output = "desc:Hewlett Packard HP Z27i CNK4040DPF" works the same as it did in 3.x. Get the strings from hyprctl monitors all.

5. Port your GTK scale. The old env = GDK_SCALE,1 becomes hl.env("GDK_SCALE", "1"). The shipped template sets this through two variables at the top of the file, and ships them at the 2x retina defaults:

   local omarchy_gdk_scale = 2
   local omarchy_monitor_scale = "auto"
   
   hl.env("GDK_SCALE", tostring(omarchy_gdk_scale))
   hl.monitor({ output = "", mode = "preferred", position = "auto", scale = omarchy_monitor_scale })

   If you run one scale for everything, keep that shape and just change the two numbers, for example 1 and 1 for a 1080p or 1440p desk. The Super + / scaling hotkeys write back into those two variables, so editing them is the supported path.

6. Reload. Save the file and Hyprland picks it up on its own config reload. If you want to force it, run hyprctl reload.

7. Delete or rename monitors.conf once the new file works, so you do not edit the dead one by mistake six months from now.

Verify it worked

Run hyprctl monitors all and read back scale, transform, at and description for each output. They should match what you wrote.

Then log out and back in. This catches the case where a value applies live but not at startup, which is the shape of issue #7066, where a transform value survives in the file but the rotation is not applied after a restart until the value is changed and changed back.

Also press Super + Return. If no keybinding responds, your Lua did not parse. See below.

Why it happens

Omarchy 4 moved the whole Hyprland configuration from .conf to Lua. ~/.config/hypr/hyprland.lua is the entry point and it pulls in your overrides with require("hypr.monitors"), which resolves to monitors.lua. There is no keyword parser left to read a .conf file.

The upgrade script omarchy-upgrade-to-quattro keeps a list it calls always_copy_config_files, and hypr/monitors.lua is on it. Those files are treated as new Quattro entry points that no older install could have, so the stock template is copied in unconditionally. The stock template is a single catch-all rule with position = "auto", scale = "auto", and omarchy_gdk_scale = 2.

monitors.conf is not on the retire list, so it is neither backed up nor removed. That is the whole bug. daventhedude documented this in issue #6911: the old file stays on disk, nothing renames it, and the upgrade summary never mentions it, so you get no hint that your display settings stopped applying. Their three-monitor setup came up with a portrait panel in landscape, wrong positions, and GTK apps at 2x on 1440p.

That issue was still open on 2026-09-16. The filename monitors.conf does not appear anywhere in the 4.0.4 tree, not in the upgrade script and not in any migration. The only attention the old ~/.config/hypr/*.conf files get is a temporary shim the upgrade script builds so the still-running 3.x session does not break on reload mid-upgrade. Nothing reads them afterwards.

If that did not work

Nothing responds to the keyboard after you edit the file. A syntax error or runtime error in monitors.lua aborts the Lua thread before require("hypr.bindings") runs, so the desktop starts with a wallpaper and a bar but no shortcuts at all. codyoss filed this as #9721, still open. Get a TTY with Ctrl + Alt + F2, fix the file, or restore the shipped default with omarchy-refresh-config hypr/monitors.lua, which backs your version up first.

A scale change snaps back within a second or two. This is the known interaction between explicit per-output rules and the scaling tool. omarchy-hyprland-monitor-scaling applies the new scale live with hyprctl eval, then persists it by rewriting only the omarchy_monitor_scale variable or the wildcard output = "" rule. With explicit hl.monitor({ output = "eDP-1", ... }) rules in the file, that goes wrong in one of two ways. If you kept the stock catch-all above your rules, the variable does get rewritten, but the file write triggers a config reload and your explicit rule overrides the catch-all again, which is what Douda traced in #7242. If you removed the catch-all, the sed finds nothing to rewrite and silently no-ops, and on a laptop with an external screen the clamshell poller re-applies the file value every couple of seconds, which RonRayReed traced in #8103 using ~/.local/state/omarchy/monitor-scaling.log. Either way the fix is the one RonRayReed gives: edit the scale in the explicit rule and reload, rather than using the Display panel or the hotkey. Both issues were still open on 2026-09-16.

Your cursor gets stuck between two screens. If you ported absolute positions like 1920x0 and then changed a scale, the logical size of that output shrank and left a dead zone. syskey8 wrote this up in discussion #8213 and proposed relative positions such as position = "auto-right" in PR #8362. That PR was still open and unmerged on 2026-09-16, and the 4.0.4 template still ships position = "auto", so you have to make this change yourself.

You are copying a 3.x guide that says hyprctl keyword monitor .... That call is rejected under the Lua parser with keyword can't work with non-legacy parsers. Use hyprctl eval with an hl.monitor({ ... }) call instead, which is what the Omarchy monitor scripts do.

Related

The manual chapter on monitors covers scaling values and the clamshell behaviour on 4.x. For the same silent replacement applied to your shortcuts, see custom keybindings lost after Quattro. For layouts that refuse to stick across reboots or docking, see multi-monitor layout not saved and multi-monitor. For apps that came back huge or blurry after the GDK_SCALE default changed, see fractional scaling blurry or huge apps. The broader port is covered in Hyprland conf to Lua migration and 3 to 4 Quattro.