"It doesn't work" Troubleshooting Checklist

You tried to screen-share and got either a completely black window, or a composite of all your Xwayland windows. This indicates the screensharer is falling back to X11 screensharing instead of using the xdg-desktop-portal screensharing stack. Or maybe you have a screencast that's stuck in the "paused" state, or some other problem.

This page contains a checklist to verify you've set up xdg-desktop-portal-wlr and the rest of the screensharing software stack correctly. If you want a more in-depth explanation of why things might not work out of the box look at systemd user services and environment page

1. Does the screen-sharing application support PipeWire for screen-sharing?

   For Firefox and Chromium, upstream's binaries link to the PipeWire 0.2 client library, whereas your actual PipeWire service is likely to be 0.3. If this is the case for you, check if your distro has a package for the PipeWire compat client library; this library allows programs to use the 0.2 client API to talk to the 0.3 service. Alternatively, some distros patch Firefox and/or Chromium to use PipeWire 0.3 directly. Check this table for what your distro does.

   For Firefox, also ensure the media.peerconnection.enabled flag in about:config is set to true and not false.

   For Chromium, also ensure the WebRTC PipeWire support flag at chrome://flags/#enable-webrtc-pipewire-capturer is set to Enabled.

2. Is the PipeWire service running?

   systemctl --user status pipewire.socket pipewire should show active (running) for both.

   If you installed PipeWire just for the sake of xdpw, make sure to run systemctl --user enable pipewire.socket so that it starts automatically on demand.

3. Is the Pipewire Multimedia Session Manager service running?

   systemctl --user status pipewire-media-session should show active (running).

   If the service does not exist, your distro may package it as a separate package named something like pipewire-media-session. Screencasts will be stuck in the "paused" state without a session manager.

   If you installed PipeWire just for the sake of xdpw, make sure to run systemctl --user enable pipewire-media-session so that it starts automatically when you log in.

4. Is the xdp service running?

   systemctl --user status xdg-desktop-portal should show active (running).

5. Does the xdp service know your wayland socket?

   env | grep '^WAYLAND_DISPLAY=' will show the value of the WAYLAND_DISPLAY environment variable set by your Wayland compositor.

   < "/proc/$(pidof xdg-desktop-portal)/environ" tr '\0' '\n' | grep '^WAYLAND_DISPLAY=' should print the same value. If it does not print anything, run:

   # Import the WAYLAND_DISPLAY env var from sway into the systemd user session.
   dbus-update-activation-environment --systemd WAYLAND_DISPLAY XDG_CURRENT_DESKTOP=$compositor_name
   
   # Stop any services that are running, so that they receive the new env var when they restart.
   systemctl --user stop pipewire pipewire-media-session xdg-desktop-portal xdg-desktop-portal-wlr
   systemctl --user start pipewire-media-session

   Replace the "$compositor_name" in XDG_CURRENT_DESKTOP=$compositor_name with the name of your compositor, according to what it's called in the UseIn= line of /usr/share/xdg-desktop-portal/portals/wlr.portal. That is, XDG_CURRENT_DESKTOP=sway for sway, XDG_CURRENT_DESKTOP=Wayfire for wayfire, and XDG_CURRENT_DESKTOP=river for river.

   You should use your compositor's method for autostart commands to run those commands when the compositor starts:

   • For sway, put them in a script that is execd from your sway config. Because the commands must run in sequence, you should put them in a script rather than execing them individually, since sway runs individual exec'd commands in parallel.

   • For Wayfire, TODO EDIT ME IF YOU KNOW HOW.

   • For river, TODO EDIT ME IF YOU KNOW HOW.

6. Does the xdp service know what your compositor is?

   < "/proc/$(pidof xdg-desktop-portal)/environ" tr '\0' '\n' | grep '^XDG_CURRENT_DESKTOP=' should print XDG_CURRENT_DESKTOP=$compositor_name. If it does not, running the commands suggested in the previous list item will handle it.

   If multiple portals are installed (GNOME, KDE, xdpw, etc), the xdp service looks at the XDG_CURRENT_DESKTOP env var to know which portal to use. Just like the WAYLAND_DISPLAY env var above, this env var needs to be defined on the xdp service. Technically this is only necessary if you have multiple portals installed, but it's a good idea to set it anyway.

   It's also a good idea to define XDG_CURRENT_DESKTOP=$compositor_name in the shell that you used to start your compositor, because some applications also benefit from having the env var set.

Other known problems

"I tried setting the XDG_CURRENT_DESKTOP=$compositor_name but screensharing still does not work." Have you tried running your compositor with dbus-run-session? If you are using sway, try running it with XDG_CURRENT_DESKTOP=sway dbus-run-session sway. If you are using a display manager, edit /usr/share/wayland-sessions/sway.desktop like so:

[Desktop Entry]
Name=Sway
Comment=An i3-compatible Wayland compositor
Exec=env XDG_CURRENT_DESKTOP=sway dbus-run-session sway
Type=Application