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:
See the Portal API reference for all supported portals.
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.
desktop interface 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=gtk3 on GTK based desktops and
QT_QPA_FLATPAK_PLATFORMTHEME=kde for Qt based desktops.
Electron: portal support in the Electron file chooser is being worked on.
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.
removable-mediainterface, however, does not auto-connect by default.
However, the file chooser portal works a bit differently than the home interface:
/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:
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.
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.
Last updated 5 months ago. Help improve this document in the forum.