Portals are a standardised framework allowing desktop applications to use resources outside of their sandbox. The file chooser portal, for example, opens a native file chooser on the host system. When the user selects a file, the application is granted access to that file.
Portals provide a range of common features to applications, including:
- Opening a file with a file chooser
- Opening URIs in other applications
- Preventing the device from suspend/sleep/powering off
- Sending email
- Showing notifications
- Taking screenshots and screencasts
See the Portal API reference for all supported portals.
ⓘ Portals originated from the Flatpak project, but are now a common Linux desktop standard with support from GNOME, KDE and Snapcraft. They are even used outside of sandboxes to provide a standardised API to common desktop features such as screenshots and screen casts on wayland.
How to use portals in your snap
Use the Portal API’s in your application
Unlike regular Snapcraft interfaces, portals require applications to use a new API in order to access resources. Toolkits like GTK 3 and Qt5, however, provide transparent support for portals. See Portal support in GTK 3 or Portal support in Qt5 and KDE for detailed information.
If your application is not using one of those toolkits, you will need to use the Portals API directly. See the Portals API documentation for more information.
desktopinterface to your snap
This interface gives your snap access to the portals.
Enable Portal support in your application.
GTK 3: turn on portal support in GTK 3 by setting the following environment variable:
Qt: often defaults to using portals, but you can enable it manually by changing the platform theme:
QT_QPA_PLATFORMTHEME=gtk3on GTK based desktops and
QT_QPA_FLATPAK_PLATFORMTHEME=kdefor Qt based desktops.
Electron: portal support in the Electron file chooser is being worked on.
ⓘ Both the
gnome-3-34extension and the
kde-neonextension automatically enable portal support for GTK 3 and Qt applications on GTK-based desktops. If your snap uses either extension, you only need to do step 1.
File chooser portal vs home interface⚓
- The portal gives the user complete control over what exact files your application should access while the interfaces are all-or-nothing toggles.
- The portal works with hidden files and folders in the home directory. If a user chooses a hidden file, the portal will give your application access to it. The
homeinterface does not give your app access to hidden files and folders in the home directory for security reasons. Note that the
homeinterface does give access to hidden files and folders elsewhere, just not in the home directory itself.
- The portal works with removable-media out of the box. If a user chooses a file from a USB stick, your app will get access to it. The
removable-mediainterface, however, does not auto-connect by default.
However, the file chooser portal works a bit differently than the home interface:
- Files are fuse-mounted to
/run/user/<uid>/doc/<hash>/in order to give your application access to it. So the path your application sees is different from the path a user chose, even though both are the same file.
The FileChooser portal also contains a few bugs:
- “Executable” permissions are currently not retained. All files will appear as non-executable to your application.
- Support for selecting folders instead of files has recently been merged and is not released yet. This will only work on distributions using
- Currently, the files are mounted even if your application has access to the file using another interface. See Improving XDG Desktop Support for the current status on fixing this issue.
org.freedesktop.portal.Flatpak.Spawnonly works in a Flatpak. If your application needs to run abritrary binaries on the host system, you can use classic confinement.
- Portal support depends on the version of
xdg-desktop-portalin the host system. Older versions do not support all portals. Repology shows what version of
xdg-desktop-portaleach distribution has and the portals NEWS file explains what portals each version supports.
ⓘ See Desktop applications for more information on how to snap a desktop application.