hyprland-wiki/pages/Useful Utilities/Hyprland-desktop-portal.md

An XDG Desktop Portal (later called XDP) is a program that lets other applications communicate swiftly with the compositor through D-Bus.

It's used for stuff like e.g. opening file pickers, screen sharing.

On Wayland, it also requires an implementation. For Hyprland, you'd usually use xdg-desktop-portal-wlr (later called XDPW)

Unfortunately, due to various reasons the -wlr portal is inferior to the KDE or Gnome ones.

In order to bridge the gap, Hyprland has its own fork of XDPW that has more features, called xdg-desktop-portal-hyprland. (later called XDPH)

{{< hint type=important >}} You don't need XDPH. Hyprland will work with XDPW, but XDPH has more features, like e.g. window sharing.

XDPH will work on other wlroots-based compositors, although limited to the XDPW features (other will be disabled) {{< /hint >}}

Installing

{{< tabs "uniqueid" >}}

{{< tab "Arch Linux" >}}

pacman -S xdg-desktop-portal-hyprland

or, for -git:

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

{{< /tab >}} {{< tab "Gentoo" >}}

Unmask dependencies

/etc/portage/profile/package.unmask

dev-qt/qtbase
dev-qt/qtwayland
dev-qt/qtdeclarative
dev-qt/qtshadertools

Apply necessary useflags

/etc/portage/package.use

dev-qt/qtbase opengl egl eglfs gles2-only
dev-qt/qtdeclarative opengl
sys-apps/xdg-desktop-portal screencast

Unmask dependencies and xdph

/etc/portage/package.accept_keywords

gui-libs/xdg-desktop-portal-hyprland 
dev-qt/qtbase
dev-qt/qtwayland
dev-qt/qtdeclarative
dev-qt/qtshadertools

btw those are the useflags that I have tested, you could also test others.

Installation

eselect repository enable guru
emaint sync -r guru
emerge --ask --verbose gui-libs/xdg-desktop-portal-hyprland

{{< /tab >}} {{< tab "Manual" >}} See The Github repo's readme.

{{</ tab >}}

{{< /tabs >}}

{{< hint type=tip >}} XDPH doesn't implement a file picker. For that, I recommend installing xdg-desktop-portal-gtk alongside XDPH. {{< /hint >}}

Usage

Should start automatically.

The most basic way of telling everything is OK is by trying to screenshare anything, or open OBS and select pipewire source. If XDPH is running, a qt menu will pop up asking you what to share.

If it doesn't, and you get e.g. slurp, then XDPW is launching. In that case, try removing XDPW.

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 exec-once it:

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

adjust the paths if 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 an exec-once.

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:

[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 might 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 most likely you are missing qt6-wayland and/or qt5-wayland.