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.
When an application makes a request through a portal, it is handled by
xdg-desktop-portal, which then forwards it to a backend implementation. This allows a clean way to provide suitable user interfaces that fit into different desktop environments, and access environment-specific APIs for requests like showing notifications or recording the screen.
Multiple backends can be installed, and they 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 that it can be used in. When a request is made,
xdg-desktop-portal will use the
XDG_CURRENT_DESKTOP environment variable to determine which backend it will use for the request. If more than one backend can be used for the current desktop, the first one in alphabetical order is chosen. If no backend for the current desktop can handle the interface, no backend is available for the current desktop, or
xdg-desktop-portal can't determine the current desktop, then it will choose the first portal in alphabetical order between all of the installed portals that support the requested interface.
For example, a Sway user may use for screen sharing support and as a fallback for all other interfaces that xdg-desktop-portal-wlr does not implement.
List of backends and interfaces
The following table lists all backends available and their support for certain common interfaces.
|Backend||File chooser||Screenshot and screen cast|
|Yes||Yes, on GNOME|
|Yes||Yes, on KDE|
|No||Yes, on Cinnamon|
|AUR||Yes||Yes, on Liri|
- works with all wlroots-based compositors, but provides extra functionality when used with Hyprland such as sharing individual windows.
- redirects requests to GNOME/GTK/KDE/LXQt backends
- allows using a terminal file manager as a file chooser
xdg-desktop-portal-wlr does not start automatically on sway
xdg-desktop-portal-wlr to work, the
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.
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 after 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
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 , and 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 .
- Portal Documentation: Lists all APIs applications and backends can implement.