Desktop portal testing notes for app developers

As some people might know, I’ve been working on bringing desktop portals to the snap ecosystem. We’re not quite at a point where it all works out of the box, but it is now possible to test without having to compile everything yourself from unmerged branches.

While it isn’t quite ready for regular end users, I think it could be interesting for application developers who want to see if portals can improve the experience of their snap. So here are instructions on testing:

Set up snapd and xdg-desktop-portal

  1. Start with an Ubuntu 18.04 system. This will eventually work on other distro releases/distros as they get the updated packages, but for now this is the easiest way to test things.

  2. Upgrade to the edge channel of the core snap to get a version of snapd with document portal support:

    sudo snap refresh --edge core
  3. Make sure xdg-desktop-portal is installed:

    sudo apt install xdg-desktop-portal xdg-desktop-portal-gtk

    If you’re testing this on another distro, make sure you’re running at least version 0.11 of each of these two packages.

  4. If you’re running the Wayland session, you will need to manually start xdg-desktop-portal-gtk by running the following in a terminal:

    GDK_BACKEND=x11 /usr/lib/xdg-desktop-portal/xdg-desktop-portal-gtk -r

    This is required due to a gnome-shell/mutter bug that causes gnome-shell to disconnect the service when it tries to associate a dialog with a confined Wayland application. The above forces the service to always use X protocol, which works but means the dialog won’t look like a proper child of a Wayland app.

  5. Make sure the xdg-document-portal service has started:

    systemctl --user start xdg-document-portal

    We will make this step automatic, but at the moment it is needed to make sure the FUSE mount at $XDG_RUNTIME_DIR/doc exists before the confined app starts.

Install the portal-test application

The portal-test app demonstrates various features of xdg-desktop-portal. I’ve created a snap of it, which can be installed with:

sudo snap install --edge portal-test

This snap is not using the home interface, so does not have direct access to your documents. However, by clicking the button next to “File Chooser”, you will be able to select any file to open from the host system. With the “Save as…” button, you can select a file name to write some content to.

The web link and screenshot portal APIs also work through the test app. I know the notifications portal API isn’t quite working correctly (we’re not associating the notification with the right desktop file yet), and I haven’t really tested the others.

Testing portals with your own application

To make use of portals in your own app, there are a few requirements:

  1. plug the desktop interface. This will allow communication with xdg-desktop-portal, and ensure that xdg-document-portal is mounted correctly in the sand box. I haven’t added portal support to the legacy unity7 interface, since this generally requires a few changes to the snap anyway.

  2. Build against a new enough GTK. You will need to use a newer version of GTK than is shipped with Ubuntu 16.04 to get most of the portal APIs working. Once core18 is ready, this shouldn’t be too difficult. For now, building against the Ubuntu Desktop team’s GNOME 3.26 backport PPA is probably the best option, possibly with the desktop-gnome-platform cloud part.

  3. Use the GtkFileChooserNative API (new in GTK 3.20) for your file open and save dialogs. This is not quite as versatile as the older API (no “extra” widget, no custom previews, etc), but is abstract enough to replace the in-process file chooser with the portal version when needed.

  4. Run your app with the GTK_USE_PORTAL=1 environment variable set. For example:

    GTK_USE_PORTAL=1 my-app

    In the portal-test snap, I turned this on permanently using the environment section:


That’s about it. If you’ve got questions, please ask them here and I’ll try to answer them the best I can.


When the following PR is merged, we can do away with step (5) of the setup above:

When this is merged, snapd master should have everything needed to properly drive the file open/save portals.