XDG Desktop Portal

Related articles
Flatpak
PipeWire#WebRTC screen sharing
From the
Flatpak documentation
:
Portals are the framework for securely accessing resources from outside an application sandbox. They provide a range of common features to applications, including: determining network status, opening a file with a file chooser, opening URIs, taking screenshots and screencasts [...]
Portals were designed for use with applications sandboxed through
Flatpak
, but any application can use portals to provide uniform access to features independent of desktops and toolkits. This is commonly used, for example, to
allow screen sharing
on
Wayland
via
PipeWire
, or to
use file open and save dialogs
on
Firefox
that use the same toolkit as your current
desktop environment
.
Installation
Install
xdg-desktop-portal
and one or more
backends
. The package includes a
systemd/User
service that will be automatically started via
D-Bus
.
Backends
When an application sends a request to the portal, it is handled by
xdg-desktop-portal
, which then forwards it to a backend implementation. This allows implementations to provide suitable user interfaces that fit into the user's desktop environments, and access environment-specific APIs for requests like opening a URI or recording the screen. Multiple backends can be installed and used at the same time. For example, a
Sway
setup may use
xdg-desktop-portal-wlr
for screen sharing support and
xdg-desktop-portal-gtk
as a fallback for all other interfaces that
xdg-desktop-portal-wlr
does not implement.
Portal backend definitions are located in
/usr/share/xdg-desktop-portal/portals/*.portal
. Each portal backend file contains a list of interfaces that it can handle, and the desktop environments which it supports.
List of backends and interfaces
The following table lists all backends available and their support for certain common interfaces.
Backend
Supported environment
Toolkit
Access portal
Account portal
App chooser portal
Background portal
Clipboard portal
Dynamic launcher portal
Email portal
File chooser portal
Global shortcuts portal
Inhibit portal
Input capture portal
Notification portal
Print portal
Remote desktop portal
Screen cast portal
Screenshot portal
Secret portal
Settings portal
Wallpaper portal
xdg-desktop-portal-cosmic
COSMIC
iced
Yes
No
No
No
No
No
No
Yes
No
No
No
No
No
No
Yes
Yes
No
Yes
No
xdg-desktop-portal-dde
Deepin
Qt
6
Yes
Yes
Yes
Yes
No
No
No
Yes
Yes
Yes
No
Yes
No
No
No
Yes
Yes
Yes
Yes
xdg-desktop-portal-gnome
GNOME
GTK
4
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
xdg-desktop-portal-gtk
generic
GTK
3
Yes
Yes
Yes
No
No
Yes
Yes
Yes
No
Yes
No
Yes
Yes
No
No
No
No
Yes
No
xdg-desktop-portal-hyprland
Hyprland
1
Qt
6
No
No
No
No
No
No
No
No
Yes
No
No
No
No
No
Yes
Yes
No
No
No
xdg-desktop-portal-kde
KDE Plasma
Qt
6
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
xdg-desktop-portal-luminous
AUR
wlroots
iced
Yes
No
No
No
No
No
No
No
No
No
No
No
No
Yes
Yes
Yes
No
Yes
No
xdg-desktop-portal-lxqt
LXQt
Qt
6
No
No
No
No
No
No
No
Yes
No
No
No
No
No
No
No
No
No
No
No
xdg-desktop-portal-phosh
Phosh
GTK
4
No
Yes
Yes
No
No
No
No
Yes
No
No
No
Yes
No
No
No
No
No
Yes
Yes
xdg-desktop-portal-td
AUR
theDesk
Qt
6
Yes
Yes
No
No
No
No
No
Yes
No
No
No
Yes
No
No
No
Yes
No
Yes
No
xdg-desktop-portal-wlr
wlroots
–
No
No
No
No
No
No
No
No
No
No
No
No
No
No
Yes
Yes
No
No
No
xdg-desktop-portal-xapp
Cinnamon
2
–
No
No
No
Yes
No
No
No
No
No
Yes
No
No
No
No
No
Yes
No
Yes
Yes
Works with all wlroots-based compositors, but provides extra functionality when used with
Hyprland
such as sharing individual windows.
Provides partial support also for
MATE
and
Xfce
.
The following packages provide a specific backend only, and not specific to a desktop environment:
darkman
implements the Settings portal backend (only for color scheme setting).
gnome-keyring
implements the Secret portal backend.
kwallet
implements the Secret portal backend.
pikeru
AUR
implements the File chooser portal backend with its own GUI application.
portty-git
AUR
implements the File chooser portal backend. It can spawn interactive terminal sessions with shell shims for selecting files using any command-line tools. Also supports headless mode for controlling dialogs from existing terminals without spawning new windows, and queue mode for pre-selecting files before applications even request the dialog.
xdg-desktop-portal-shana
AUR
implements the File chooser portal backend. It redirects requests to GNOME/GTK/KDE/LXQt backends.
xdg-desktop-portal-termfilechooser-git
AUR
implements the File chooser portal backend. It allows using a
terminal file manager
as a file chooser.
xdg-desktop-portal-termfilechooser-hunkyburrito-git
AUR
is a new fork for the now archived xdg-desktop-portal-termfilechooser-git that implements the File chooser portal backend and allows using a
terminal file manager
as a file chooser.
Configuration
When a request is made,
xdg-desktop-portal
will use the
/usr/share/xdg-desktop-portal/
DE
-portals.conf
file, where
DE
is based on the
XDG_CURRENT_DESKTOP
environment variable
. These files are provided by the desktop environments themselves and determine which backends should be used when a specific environment is running.
If you want to override the desktop environment defaults, or your desktop environment does not provide a default configuration, you may create a portal configuration file at
$XDG_CONFIG_HOME/xdg-desktop-portal/portals.conf
to determine which backends you want to use, either generally or for each individual interface. If you use multiple desktop environments, you may also create multiple
$XDG_CONFIG_HOME/xdg-desktop-portal/
DE
-portals.conf
files for each environment.
For example, if your desktop environment does not have a portal backend, and you want to use
xdg-desktop-portal-gtk
as a generic fallback but also use the LXQt file picker through
xdg-desktop-portal-lxqt
, you can use the following configuration:
~/.config/xdg-desktop-portal/portals.conf
[preferred]
default=gtk
org.freedesktop.impl.portal.FileChooser=lxqt
See
portals.conf(5)
for more information.
Force desktop environment
In some cases, such as when you have a standalone
window manager
, you might want to make
xdg-desktop-portal
to think you are using a specific desktop environment. This can be achieved by setting the
XDG_CURRENT_DESKTOP
environment variable for the
xdg-desktop-portal.service
user unit
using a
drop-in snippet
. For example, to use the backend associated with KDE:
~/.config/systemd/user/xdg-desktop-portal.service.d/override.conf
[Service]
Environment="XDG_CURRENT_DESKTOP=KDE"
Troubleshooting
Portal does not start
For
xdg-desktop-portal-wlr
and
xdg-desktop-portal-hyprland
to work, the
XDG_CURRENT_DESKTOP
and
WAYLAND_DISPLAY
environment variables have to be set in the
systemd user session
.
XDG_CURRENT_DESKTOP
has to be set to the name of your compositor, e.g.
XDG_CURRENT_DESKTOP=sway
.
WAYLAND_DISPLAY
is set automatically by the compositor.
Check whether these variables are set with
systemctl --user show-environment
. If they are not set, import these environment variables into the systemd user session and dbus by running the following commands before launching the compositor (e.g., include them in the compositor's configuration file).
$ systemctl --user import-environment WAYLAND_DISPLAY XDG_CURRENT_DESKTOP
$ dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=
compositor_name
Note
These environment variables needs to be set before the compositor starts. This is usually done through the compositor's own configuration, see its documentation for details.
Tip
Sway
provides a drop-in file which does this automatically, see
Sway#Configuration
.
Hyprland
may not automatically set these environment variables. You can specify them manually, see
Hyprland Wiki
.
See
[1]
and
[2]
for more details.
Using multiple monitors with xdg-desktop-portal-wlr
xdg-desktop-portal-wlr
requires an external chooser to select the shared monitor. By default, it looks for
slurp
,
wofi
and
bemenu
in this order. When using
slurp
, after a request for screen sharing you will be presented with a crosshair cursor and you will need to click the screen you want to share. When using
wofi
or
bemenu
, you will be presented with a menu of available displays to share. If no choosers are available,
xdg-desktop-portal-wlr
will fallback to the first monitor found. For more information, see
xdg-desktop-portal-wlr(5) § SCREENCAST OPTIONS
.
Poor font rendering in GTK applications on KDE Plasma
Some GTK apps require
xdg-desktop-portal-gtk
on Plasma in order to render font correctly. Install it and then run:
$ /usr/lib/xdg-desktop-portal --replace
GTK (possibly others) file chooser not working
If the application runs on X via
Xwayland
(easiest way to check is to run
xeyes
and see whether they follow the mouse over the application in question), then
xdg-desktop-portal-gtk
will show up on demand, but after you select the file nothing will happen. In that case adding
DISPLAY=:0
to the
xdg-desktop-portal-gtk
environment might help. To do this, you can either follow the instructions above about
import-environment
or just edit the systemd user unit file of
xdg-desktop-portal-gtk
. Alternatively, you can force the application under
Wayland
(e.g. if it is using
Electron
).
See also
Project homepage
Portal Documentation
: Lists all APIs applications and backends can implement.