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

Screen share is a black rectangle (or no picker appears) on Hyprland

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

Nearly all of this is verbatim wiki-sourced and correct. The XDPH wiki page carries the exact warning "XDPH doesn't implement a file picker. For that, it is recommended to install xdg-desktop-portal-gtk alongside XDPH", so keeping GTK is right. Screen-Sharing.md says "Ensure that the bitdepth set in your configuration matches that of your physical monitor" and Monitors.md says "Some applications do not support screen capture with 10 bit enabled", both quoted accurately, and the bitdepth = 8 fix is the wiki's own. The XWayland limitation is quoted almost word for word from Screen-Sharing.md, and the xwaylandvideobridge window_rule block (including opacity = 0.0, which the Variables table types as a string but the wiki's own example writes as a number) is copied verbatim from that page, so I am not faulting it. hl.on("hyprland.start", ...) with hl.exec_cmd() is the documented autostart form. xwaylandvideobridge is correctly labelled AUR (0.4.0-3). One real defect: /usr/share/xdg-desktop-portal/hyprland-portals.conf does not exist. I pulled both Arch package file lists: xdg-desktop-portal-hyprland ships only usr/share/xdg-desktop-portal/portals/hyprland.portal, and xdg-desktop-portal ships no *-portals.conf at all (its only matching file is the portals.conf.5 man page). Omarchy ships none either. So step 3's cp fails with 'No such file or directory' and the parenthetical claim about default routing living there is wrong.

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

Removing xdg-desktop-portal-wlr with -Rns will also take its dependencies. If any other compositor on this machine relies on it, that session loses file pickers and screen capture. Do not remove xdg-desktop-portal-gtk, because XDPH has no file picker of its own and every GTK/Electron "Open File" dialog will stop working. Dropping bitdepth from 10 to 8 loses HDR/wide-gamut output on that display.

Symptom

In Discord, Zoom, Google Meet, Teams or OBS you start a share and the other side sees a solid black rectangle: audio works, video does not. Or the Qt share picker never appears at all and the browser reports no capture sources. journalctl --user -u xdg-desktop-portal -b shows lines like No skeleton portal implementation or Failed to load portal implementation. A plain grim screenshot.png from the same session may work fine, which makes it look like the compositor is healthy.

Cause

Capture goes through a chain: app → xdg-desktop-portal → xdg-desktop-portal-hyprland (XDPH) → Hyprland's screencopy → PipeWire. Every link breaks in its own way:

  1. pipewire, wireplumber or xdg-desktop-portal-hyprland is not running.
  2. XDPH was D-Bus-activated before WAYLAND_DISPLAY / XDG_CURRENT_DESKTOP / HYPRLAND_INSTANCE_SIGNATURE reached the activation environment, so it cannot talk to the compositor and hands back an empty stream.
  3. A second portal backend is installed (xdg-desktop-portal-wlr, -gnome, -kde) and wins the ScreenCast interface, or a stale ~/.config/xdg-desktop-portal/portals.conf from an old setup routes it somewhere dead.
  4. **10-bit output.** The Hyprland Monitors page states outright that "some applications do not support screen capture with 10 bit enabled", and the Screen Sharing page tells you to make sure bitdepth matches your physical monitor. A bitdepth = 10 monitor line is one of the most common causes of a black capture.
  5. The capturing app is running under XWayland (the Discord desktop client, older Skype). Per the Hyprland wiki it can then only see other XWayland windows, and it cannot capture a whole screen or a native Wayland window.

Fix

Steps 1, 2 and 4 through 8 stand as written. Two things change.

**Step 2's parenthetical:** keep xdg-desktop-portal-gtk, because XDPH does not implement a file picker and the Hyprland wiki recommends GTK alongside it. XDPH's own interface declaration lives in /usr/share/xdg-desktop-portal/portals/hyprland.portal. There is **no** /usr/share/xdg-desktop-portal/hyprland-portals.conf on Arch or Omarchy.

**Step 3: reset a stale user portals.conf.** Deleting it is the fix. There is no packaged Hyprland file to copy back, so just remove yours and let xdg-desktop-portal fall back to its built-in resolution:


rm -f ~/.config/xdg-desktop-portal/portals.conf
rm -f ~/.config/xdg-desktop-portal/hyprland-portals.conf   # if you made one

If you want an explicit routing file instead of the default, write it yourself rather than copying a file that does not exist:


# ~/.config/xdg-desktop-portal/portals.conf
[preferred]
default=hyprland;gtk
org.freedesktop.impl.portal.ScreenCast=hyprland
org.freedesktop.impl.portal.Screenshot=hyprland
org.freedesktop.impl.portal.FileChooser=gtk

See man 5 portals.conf for the syntax. Then restart the chain as in step 5:


systemctl --user restart pipewire wireplumber
systemctl --user restart xdg-desktop-portal-hyprland xdg-desktop-portal

Verify

Starting a share pops the Qt hyprland-share-picker window, and the receiving side sees live content. grim /tmp/t.png && xdg-open /tmp/t.png produces a non-black image (proves screencopy itself is fine). In OBS, a PipeWire Screen Capture source shows a live preview.

Sources

screen-share-black-portal-hyprland