Screen share is a black rectangle (or no picker appears) on Hyprland
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.
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:
pipewire,wireplumberorxdg-desktop-portal-hyprlandis not running.- XDPH was D-Bus-activated before
WAYLAND_DISPLAY/XDG_CURRENT_DESKTOP/HYPRLAND_INSTANCE_SIGNATUREreached the activation environment, so it cannot talk to the compositor and hands back an empty stream. - A second portal backend is installed (
xdg-desktop-portal-wlr,-gnome,-kde) and wins theScreenCastinterface, or a stale~/.config/xdg-desktop-portal/portals.conffrom an old setup routes it somewhere dead. - **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
bitdepthmatches your physical monitor. Abitdepth = 10monitor line is one of the most common causes of a black capture. - 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
- https://wiki.hypr.land/Useful-Utilities/Screen-Sharing/
- https://github.com/hyprwm/hyprland-wiki/blob/main/content/Hypr%20Ecosystem/xdg-desktop-portal-hyprland.md
- https://github.com/hyprwm/hyprland-wiki/blob/main/content/Configuring/Basics/Monitors.md
- https://gist.github.com/brunoanc/2dea6ddf6974ba4e5d26c3139ffb7580
- https://github.com/hyprwm/hyprland-wiki/blob/main/content/Nvidia/_index.md