Skip to content
Hypr Ecosystem
xdg-desktop-portal-hyprland

xdg-desktop-portal-hyprland

An XDG Desktop Portal is a program that lets other applications communicate with the compositor through D-Bus.

A portal implements certain functionalities, such as opening file pickers or screen sharing.

xdg-desktop-portal-hyprland is Hyprland’s xdg-desktop-portal implementation. It allows for screensharing, global shortcuts, etc.

Note

Throughout this document, xdg-desktop-portal-hyprland will be referred to as XDPH.

Warning

XDPH doesn’t implement a file picker. For that, it is recommended to install xdg-desktop-portal-gtk alongside XDPH.

Installing 

pacman -S xdg-desktop-portal-hyprland

or, for -git:

yay -S xdg-desktop-portal-hyprland-git

Usage

Warning

The systemd xdg-desktop-portal.service may require an active graphical-session.target, which Hyprland doesn’t start by default. See systemd to set that up.

XDPH is automatically started by D-Bus, once Hyprland starts.

To check if everything is OK is, try to screenshare anything, or opening OBS and select the PipeWire source.
If XDPH is running, a Qt menu will pop up asking you what to share.

XDPH will work on other wlroots compositors, but features available only on Hyprland will not work (e.g. window sharing).

For a nuclear option, you can use this script and autostart it:

#!/bin/sh
sleep 1
killall -e xdg-desktop-portal-hyprland
killall xdg-desktop-portal
/usr/lib/xdg-desktop-portal-hyprland &
sleep 2
/usr/lib/xdg-desktop-portal &

Adjust the paths if they’re incorrect.

Share Picker Doesn’t Use the System Theme

Try one or both:

dbus-update-activation-environment --systemd --all
systemctl --user import-environment QT_QPA_PLATFORMTHEME

If it works, add it to your config in autostarts.

Using the KDE File Picker With XDPH

XDPH does not implement a file picker and uses the GTK one as a fallback by default (see /usr/share/xdg-desktop-portal/hyprland-portals.conf). If you want to use the KDE file picker but let XDPH handle everything else, create a file ~/.config/xdg-desktop-portal/hyprland-portals.conf with the following content:

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

You can read more about this in the xdg-desktop-portal documentation in the Arch Wiki. Note that some applications like Firefox may require additional configuration to use the KDE file picker.

Debugging

If you get long app launch times, or screensharing does not work, consult the logs.

systemctl --user status xdg-desktop-portal-hyprland

If you see a crash, it’s likely you are missing either qt6-wayland or qt5-wayland.

If the portal does not autostart, does not function when manually started, and does not produce any error logs, it’s very likely your XDG env variables are messed up

Configuration

Example:

screencopy {
    max_fps = 60
}

Config file ~/.config/hypr/xdph.conf allows for these variables:

category screencopy

Variable Description Type Default
max_fps Maximum fps of a screensharing session.
0 means no limit.		 int 120
allow_token_by_default If enabled, will tick the “Allow restore token” box by default. bool false
custom_picker_binary If non-empty, will use that binary as your share picker.
Please note that it has to conform to the stdout selection layout of hyprland-share-picker.		 string "hyprland-share-picker"
force_shm If enabled, will skip DMA-BUF and always use SHM for screensharing. SHM is slower than DMA-BUF (especially at high resolutions) but can work around DMA-BUF allocation failures on multi-GPU systems. bool false
cursor_mode Default cursor mode for clients that don’t specify a mode, e.g. browsers. Any implemented mode for XDG ScreenCast Portal, i.e. 1=hidden or 2=embedded. Defaults to protocol default (hidden). int 0
Last updated on
hyprlockhyprsysteminfo