OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
display-monitors medium very-common DISPUTE

Mirroring one display onto another, and why the mirror vanishes from hyprctl monitors

omarchyomarchy-4hyprlandwaylandarchendeavouroscachyosmanjarolaptopdesktop
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Re-checked every claim against Hyprland v0.56.2 source rather than only the wiki, plus the installed omarchy 4.0.2-1 and hyprland 0.56.2-1 packages on this workstation. The core of the record holds and is now proven at source level, not just documented. hyprctl monitors really does hide mirrors: monitorsRequest in src/debug/HyprCtl.cpp line 327 picks allMonitors() for monitors all and monitors() otherwise, and CMonitorStateTracker in src/state/MonitorState.cpp lines 33 to 36 erases anything where isMirror() is true and skips outputs that are not enabled or are mirrors. The Lua half holds too: hlGetMonitors in src/config/lua/bindings/LuaBindingsQuery.cpp iterates monitors(), so mirrors and disabled outputs are absent, and the shipped stub /usr/share/hypr/stubs/hl.meta.lua line 847 declares get_monitors fun(): HL.Monitor[] with no argument, confirming PR 14693 (merged 2026-08-21) is still not in a tagged release. v0.56.2 released 2026-08-05 is still the newest upstream release, so the first-pass note's forward-looking warning is still true and worth keeping. Discussion 14645 was read in full and does support the claim: the author reports hl.get_monitor(id) returning nil for a mirrored output, and a commenter states hl.get_monitors() only lists enabled monitors. The mirror field and both example forms match content/configuring/core/monitors/_index.md in the wiki repo, including the 'will not re-render' and squish-and-stretch wording, and the stub carries ---@field mirror? string at line 579. Reading /usr/share/omarchy/bin/omarchy-hyprland-monitor-internal-mirror on the installed package confirms on, off, toggle and recover, the ^(eDP|LVDS|DSI)- exclusion, the internal-monitor-mirror.lua state file, forcing the internal-monitor-disable toggle off first, and the trailing hyprctl reload. The keybind is at default/hypr/bindings/utilities.lua line 33 as claimed. omarchy-hyprland-toggle-enabled is a one-line file test on the flag path, so the verify claim is exact. Two defects. First, the symptom says overlapping positions make Hyprland 'shove one aside'. It does not. CMonitorLayoutController::checkOverlapsAndNotify in src/state/MonitorLayoutController.cpp logs an error and raises a 15 second warning notification, then breaks. The overlap is left in place, which is worse than the record implies, because the user sees a warning and two genuinely overlapping outputs. Second, the record presents the Omarchy toggle as the Omarchy 4 way to mirror without saying it is laptop only. omarchy-hyprland-monitor-laptop returns the first output matching ^(eDP|LVDS|DSI)-, so on a desktop INTERNAL is empty and the script exits 1 with a 'No laptop monitor found to mirror' notification. The menu entry at default/omarchy/omarchy-menu.jsonc line 70 is gated on omarchy-hw-laptop, but the keybind is not, so a desktop user following this record gets a failure notification and no explanation. The hand-written mirror rule is the answer on a desktop. One dead source found and replaced: the cited raw wiki URL under content/Configuring/Basics/Monitors.md returns 404 because the wiki was reorganised to content/configuring/core/monitors/_index.md. The three basecamp/omarchy raw URLs still redirect and still serve, but the repo was renamed to omacom/omarchy, so they are swapped for canonical ones rather than deleted. NOT exercised: nothing was configured, no mirror was enabled, no reload or dispatch was run, and this workstation has a single connected output (HDMI-A-1, Microstep MSI G274QPF), so the disappearance from hyprctl monitors was confirmed from source and from Omarchy's own comment, not observed live.

The cause above was not rewritten and may still contain the error described. The fix below is the corrected version.
RISK

If you write a mirror rule for the only external output and then disable the source panel (e.g. the internal-display toggle), you can end up with no monitor showing anything. Omarchy guards against this by forcing the internal-monitor-disable toggle off before enabling the mirror. If you hand-roll it, keep a TTY available (Ctrl+Alt+F2) and be ready to run hyprctl reload after reverting monitors.lua. A catch-all output = "" mirror rule also captures every future display, including a second desk monitor you wanted as an extended screen.

Symptom

I need to mirror my laptop screen onto a projector for a presentation, or mirror the internal panel while docked. Giving both monitors the same position = "0x0" does not mirror anything. Hyprland raises a warning notification that the layout is invalid and then leaves both outputs sitting on top of each other. And once I do get a real mirror working, the mirrored output disappears completely from hyprctl monitors, so my status bar and my own scripts think the monitor was unplugged. hl.get_monitors() in Lua does not list it either, and hl.get_monitor(id) on it returns nil.

Cause

Mirroring is not done with positions. It is a dedicated mirror field on the monitor rule that names the output to copy. Once an output is mirroring another it is no longer an independent output in the layout, so Hyprland deliberately omits it from hyprctl monitors. It only appears in hyprctl monitors all. The same applies to the Lua API: hl.get_monitors() returns only enabled, non-mirrored outputs, which is why HL.Monitor.is_mirror reads as useless (hyprwm/Hyprland discussion #14645). Mirroring is also a straight scanout copy, not a re-render: a 1080p source mirrored onto a 4K panel stays 1080p, and mismatched aspect ratios get squished or stretched.

Fix

**Mirror by hand (Hyprland 0.55+ Lua, ~/.config/hypr/monitors.lua)**

The rule goes on the output that should *show* the copy, and mirror names the source:


-- eDP-1 is the real output; HDMI-A-1 shows a copy of it
hl.monitor({ output = "eDP-1",    mode = "preferred", position = "0x0",  scale = 1 })
hl.monitor({ output = "HDMI-A-1", mode = "preferred", position = "auto", scale = 1, mirror = "eDP-1" })

On a desktop the same shape works with two external outputs. Read your own connector names out of hyprctl monitors all first rather than copying eDP-1.

A catch-all so *any* newly plugged screen mirrors the source (useful for projectors whose connector name you do not know in advance):


hl.monitor({ output = "", mode = "preferred", position = "auto", scale = 1, mirror = "eDP-1" })

Apply without restarting the session:


hyprctl reload

**On Omarchy 4 there is a shipped toggle, but it is laptop only.** It mirrors the internal panel onto the first external output, so it does nothing on a desktop. Super + Ctrl + Alt + Delete, or from a terminal:


omarchy-hyprland-monitor-internal-mirror toggle   # on/off/toggle/recover

It reads the internal panel from omarchy-hyprland-monitor-laptop, which matches ^(eDP|LVDS|DSI)-. With no such output it sends a "No laptop monitor found to mirror" notification and exits 1. Otherwise it picks the first active non-eDP/LVDS/DSI output, forces the internal-monitor-disable toggle off, writes a generated rule to ~/.local/state/omarchy/toggles/hypr/internal-monitor-mirror.lua, and runs hyprctl reload. The Omarchy menu entry for it is gated on omarchy-hw-laptop and is hidden on a desktop, but the keybind is not gated, so pressing it on a desktop just produces the notification.

Turn it off explicitly with:


omarchy-hyprland-monitor-internal-mirror off

**Seeing the mirrored output again.** Plain monitors will not show it. Use:


hyprctl monitors all
hyprctl monitors all -j | jq -r '.[] | "\(.name)\tdisabled=\(.disabled)\tmirrorOf=\(.mirrorOf)\t\(.width)x\(.height)@\(.refreshRate)"'

This is not an accident of the CLI. In Hyprland 0.56.2 the compositor keeps two lists, and the one behind plain monitors has every disabled and every mirroring output removed from it. hyprctl monitors all reads the other list. Omarchy's own omarchy-hyprland-monitor-modeless documents the same thing: *"Mirrors are absent from plain monitors, hence all plus an explicit disabled filter."* Any script of yours that counts monitors must use monitors all too, or it will conclude a mirrored screen is gone.

The Lua API has the same blind spot and no all option in 0.56.2: hl.get_monitors() takes no arguments and returns only enabled, non-mirrored outputs, and hl.get_monitor(id) on a mirror returns nil. Track mirror state yourself, for example by testing for the Omarchy toggle file, until a release ships the table form of hl.get_monitors.

**Expectation setting:** the mirror is a scanout copy, not a re-render. Mirroring 1920x1080 onto a 3840x2160 panel gives you a 1080p image, and mirroring 16:10 onto 16:9 will stretch. If you need a sharp image on the projector, set both outputs to the same mode instead of mirroring, or accept the source resolution.

Verify

hyprctl monitors should now list only the source output, while hyprctl monitors all lists both. Confirm the copy is live by moving a window. It should appear on both screens simultaneously. On Omarchy, omarchy-hyprland-toggle-enabled internal-monitor-mirror exits 0 while mirroring is on.

Sources

mirroring-a-display-and-hidden-mirror-outputs