OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
wayland-compat medium common DISPUTE

Replace an X11-era screenshot tool that breaks on multiple monitors

omarchyarchendeavouroscachyosmanjarohyprlandwaylanddesktoplaptop
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Checked on this Omarchy 4 workstation (omarchy 4.0.2-1, Hyprland 0.56.2, two real outputs: HDMI-A-1 at 0x0 2560x1440 and vncpanel at 2560x0 1920x1080) and against both cited pages plus Flameshot upstream. Four defects. (1) The record works around the distribution. Omarchy 4 binds PRINT to omarchy-capture-screenshot in /usr/share/omarchy/default/hypr/bindings/utilities.lua, and that script drives omarchy-capture-region, which reads hyprctl monitors -j, divides width and height by scale and swaps them for transform 1 and 3, so it is already the multi-monitor answer. grim 1.5.0-2, slurp 1.5.0-2 and wl-clipboard 1:2.3.0-1 are already installed, so the pacman line installs nothing. The record buries this in one sentence after telling the reader to add a duplicate bind. (2) The Flameshot window rules are not what the cited source says. The 0.54 FAQ (fetched, HTTP 200) has three rules in the form windowrule = match:title flameshot, float true, move 0 0 and suppress_event fullscreen. The record's five rules with class:flameshot, pin, noinitialfocus and monitor 1 appear on neither cited page, and the unversioned Screenshots and Recording page dropped the Flameshot rules entirely in the 2026-08-29 wiki restructure (hyprwm/hyprland-wiki commit cba1dbc5), leaving only 'make sure your desktop portal setup is working'. (3) XDG_CURRENT_DESKTOP=sway flameshot gui is misapplied. Flameshot's own docs/UsageHyprlandSwayWlroots.md scopes that to Sway and river with xdg-desktop-portal-wlr, exported before the compositor launches. Confirmed here that xdg-desktop-portal-wlr is not installed (pacman -Q fails) while xdg-desktop-portal-hyprland 1.4.1-1 is, so on Omarchy the trick points at a missing backend. Upstream's actual multi-monitor answer is flameshot screen --number <id> --edit driven by hl.get_active_monitor(), with hl.window_rule pin and float. (4) The cause blamed X screen geometry. Flameshot 14 on Wayland goes through the portal, and the overlay is an ordinary toplevel the compositor places on one output, which is the real mechanism. Flameshot is not abandoned: extra 14.0.0-1, last updated 2026-06-11 per archlinux.org JSON. Both cited URLs still resolve and both are still relied on, so neither is removed. NOT exercised: I did not run omarchy-capture-screenshot, slurp, grim or flameshot, because every one of them takes over the operator's screen or writes a file, so the multi-monitor capture itself is argued from the scripts and the monitor geometry rather than from a capture I took.

The cause above was rewritten on 2026-09-13 to match this note; the fix was corrected by the audit itself.
RISK

Do not export XDG_CURRENT_DESKTOP=sway on Hyprland, on the command line or session wide. It selects which portal backend every request from that process reaches. Omarchy 4 ships xdg-desktop-portal-hyprland and does not install xdg-desktop-portal-wlr, so the setting points at a backend that does not exist. Set session wide it breaks screen sharing for every application, not only the screenshot tool.

Symptom

Flameshot (or another X11-era screenshot tool) opens on the wrong monitor, captures only one screen, produces a warped image when you Ctrl+C from its GUI, or hangs the session so Esc and clicks do nothing while the cursor still moves.

Cause

Flameshot has no direct way to read the screen on Wayland. It asks xdg-desktop-portal for the capture, then draws its own selection and annotation overlay as an ordinary toplevel window. Hyprland places that toplevel on one output like any other window, so the overlay appears on the wrong monitor, covers only that monitor, and the region the user drags is measured against one output instead of the whole layout. Scale and transform make it worse: a HiDPI or rotated output shifts the coordinates the overlay reports against the pixels the portal returned, which is where the warped image comes from. Upstream Flameshot documents the same conclusion and answers it with a per-monitor capture plus window rules rather than a whole-desktop grab. Omarchy 4 does not hit any of this, because it ships its own capture stack that reads the real monitor rectangles out of Hyprland before it captures anything.

Fix

**On Omarchy 4 the fix is to stop working around the distribution.** Omarchy already ships a multi-monitor-aware capture stack and already binds it. PRINT runs omarchy-capture-screenshot, defined in /usr/share/omarchy/default/hypr/bindings/utilities.lua, and SUPER + CTRL + C opens the capture menu. grim, slurp, wl-clipboard, hyprpicker and jq are all installed already, so there is nothing to add.


omarchy-capture-screenshot            # smart pick, saves to file and clipboard
omarchy-capture-screenshot region     # freeform, can cross a monitor boundary
omarchy-capture-screenshot fullscreen # the focused monitor, no interaction
omarchy-capture-screenshot region copy # clipboard only, no file

It is multi-monitor aware by construction. omarchy-capture-region reads hyprctl monitors -j and divides width and height by scale, swapping them for transform 1 and 3, so a scaled or rotated output produces the right rectangle. slurp opens one selection layer per monitor, so a freeform drag can span outputs, and grim -g composites the result.

Screenshots land in $OMARCHY_SCREENSHOT_DIR, else $XDG_PICTURES_DIR, else ~/Pictures. The editor is $OMARCHY_SCREENSHOT_EDITOR, default tensaku-edit.

To put it on a different key, override in ~/.config/hypr/bindings.lua:


o.bind("SUPER + SHIFT + S", "Screenshot", "omarchy-capture-screenshot")

**On plain Arch or another Hyprland install**, install the native Wayland tools and bind them yourself.


sudo pacman -S --needed grim slurp wl-clipboard

Hyprland 0.55 and newer, Lua config (~/.config/hypr/hyprland.lua):


hl.bind("Print", hl.dsp.exec_cmd('grim -g "$(slurp -d)" - | wl-copy'))

Hyprland 0.54 and older, hyprlang config (~/.config/hypr/hyprland.conf):


bind = , Print, exec, grim -g "$(slurp -d)" - | wl-copy
bind = SHIFT, Print, exec, grim -g "$(slurp -d)" ~/Pictures/$(date +%Y-%m-%d_%H-%M-%S).png

To capture one whole output with no picker, name it. Read the connector names first:


hyprctl monitors all | grep '^Monitor'

On the machine this was checked on that prints Monitor HDMI-A-1 (ID 0) and Monitor vncpanel (ID 1), so:


grim -o HDMI-A-1 ~/Pictures/hdmi.png

**Alternative: keep Flameshot.** It is current in extra (14.0.0-1, updated 2026-06-11), not abandoned. Upstream says it works on Hyprland with little configuration as long as xdg-desktop-portal-hyprland is installed and running, which it is on Omarchy 4 (1.4.1-1). The multi-monitor answer is to capture one monitor at a time rather than the whole desktop, using the current Lua API:


hl.bind("Print", function()
  local mon = hl.get_active_monitor()
  local n = mon and mon.id or 0
  hl.exec_cmd("flameshot screen --number " .. n .. " --edit")
end)

hl.window_rule({
  match    = { class = "flameshot" },
  no_anim  = true,
  pin      = true,
  float    = true,
  decorate = false,
  no_blur  = true,
  no_shadow = true,
})
hl.window_rule({
  match = { class = "flameshot", title = "flameshot" },
  move  = { 0, 0 },
})

If capture fails outright, the problem is the portal, not Flameshot. Check that exactly one screenshot backend is running:


systemctl --user status xdg-desktop-portal-hyprland
busctl --user list | grep portal

**Do not set XDG_CURRENT_DESKTOP=sway on Hyprland.** That advice belongs to Sway and river, where it is exported before the compositor starts so that xdg-desktop-portal-wlr is selected. xdg-desktop-portal-wlr is not installed on Omarchy 4, so forcing sway only points the portal at a backend that is not there.

Verify

On Omarchy 4, press PRINT, drag a region across the boundary between two monitors, and confirm the saved PNG in ~/Pictures matches what you selected and that wl-paste --list-types prints image/png. On plain Arch, press the bind you added and run the same check. To confirm the stack sees the real layout, compare hyprctl monitors all | grep '^Monitor' against the geometry in the captured image.

Sources

screenshot-tool-broken-multimonitor