Get Screen Sharing to Work on Wayland

Screen sharing on Wayland has a reputation for being broken, but that reputation is mostly outdated. The modern stack—PipeWire, xdg-desktop-portal, and compositor-specific backends—works well on GNOME and KDE Plasma, and is catching up fast on wlroots-based compositors like Sway and Hyprland. What trips people up is a mismatch between the portal backend, the PipeWire session, or a browser that hasn't been told to use the right API. This guide fixes all of that.

How Wayland Screen Sharing Actually Works

Under X11, any application could read any window's pixels. Wayland forbids that by design. Instead, the compositor exposes a PipeWire screencast stream gated behind a portal. The flow is:

1. An app requests a screen share via the org.freedesktop.portal.ScreenCast D-Bus interface.
2. xdg-desktop-portal forwards the request to a compositor-specific backend (e.g., xdg-desktop-portal-gnome or xdg-desktop-portal-kde).
3. The compositor shows a picker dialog and creates a PipeWire node.
4. The app consumes that PipeWire stream as video.

Every broken link in that chain produces a different symptom. The sections below address each one.

Step 1: Verify PipeWire Is Running

PipeWire should be running as a user service. Check:

systemctl --user status pipewire pipewire-pulse wireplumber

All three should show active (running). If any are missing or dead, enable and start them:

systemctl --user enable --now pipewire pipewire-pulse wireplumber

On Fedora 38+ and Ubuntu 22.04+ this is already the default. On Arch you may need to install the packages first:

sudo pacman -S pipewire pipewire-pulse wireplumber

On Debian 12 / Ubuntu 22.04:

sudo apt install pipewire pipewire-pulse wireplumber

Step 2: Install the Right xdg-desktop-portal Backend

The base xdg-desktop-portal package is compositor-agnostic. You also need the backend that matches your desktop environment or compositor.

GNOME (including Ubuntu's default session)

# Debian / Ubuntu
sudo apt install xdg-desktop-portal xdg-desktop-portal-gnome

# Fedora
sudo dnf install xdg-desktop-portal xdg-desktop-portal-gnome

# Arch
sudo pacman -S xdg-desktop-portal xdg-desktop-portal-gnome

KDE Plasma

# Debian / Ubuntu
sudo apt install xdg-desktop-portal xdg-desktop-portal-kde

# Fedora
sudo dnf install xdg-desktop-portal xdg-desktop-portal-kde

# Arch
sudo pacman -S xdg-desktop-portal xdg-desktop-portal-kde

Sway / Hyprland / other wlroots compositors

# Debian / Ubuntu
sudo apt install xdg-desktop-portal xdg-desktop-portal-wlr

# Fedora
sudo dnf install xdg-desktop-portal xdg-desktop-portal-wlr

# Arch
sudo pacman -S xdg-desktop-portal xdg-desktop-portal-wlr

Note: xdg-desktop-portal-wlr supports output sharing (whole monitors) but not individual window sharing—that is a protocol limitation, not a bug. The xdg-desktop-portal-hyprland AUR package adds window picking for Hyprland specifically.

Step 3: Ensure the Portal Service Starts Correctly

After installation, restart the portal and check for conflicts. Having two backends registered for the same interface causes silent failures.

systemctl --user restart xdg-desktop-portal
systemctl --user status xdg-desktop-portal

List which portal implementations are loaded:

ls /usr/share/xdg-desktop-portal/portals/

Each .portal file declares which interfaces and desktop environments it handles. If you see both gnome.portal and gtk.portal, that is normal—they cooperate. What causes problems is having wlr.portal active inside a GNOME session, or vice versa.

If you have multiple backends installed and the wrong one is winning, set XDGP_BACKENDS explicitly. For GNOME inside a custom session:

# Add to ~/.config/environment.d/portals.conf
XDG_CURRENT_DESKTOP=GNOME

The portal daemon reads XDG_CURRENT_DESKTOP to pick the right backend.

Step 4: Fix Chromium-Based Browsers

Chrome, Chromium, Edge, Brave, and Electron apps can use PipeWire screencasting, but the flag or launch option must be set.

Chrome / Chromium / Brave / Edge

Open chrome://flags (substitute your browser's scheme) and enable:

• WebRTC PipeWire support — search for pipewire
• Ozone platform hint — set to Auto or Wayland

Alternatively, pass flags at launch. Create or edit the desktop entry override:

mkdir -p ~/.config/chrome-flags.conf
echo --ozone-platform=wayland >> ~/.config/chrome-flags.conf
echo --enable-webrtc-pipewire-capturer >> ~/.config/chrome-flags.conf

For Chromium the file is ~/.config/chromium-flags.conf. For Brave it is ~/.config/brave-flags.conf. These files are read automatically on launch.

Firefox

Firefox on Wayland uses PipeWire natively since version 116. Make sure it's running as a Wayland app:

echo MOZ_ENABLE_WAYLAND=1 >> ~/.config/environment.d/firefox.conf

Then log out and back in. In about:config, verify media.webrtc.hw.h264.enabled and media.peerconnection.video.enabled are both true (they are by default).

Step 5: OBS Studio Screen Capture

OBS 29+ has built-in PipeWire support. Install the current release—distro packages may be older than needed.

# Ubuntu (via PPA for latest stable)
sudo add-apt-repository ppa:obsproject/obs-studio
sudo apt update && sudo apt install obs-studio

# Fedora
sudo dnf install obs-studio

# Arch
sudo pacman -S obs-studio

In OBS, add a source: Sources → + → Screen Capture (PipeWire). A compositor picker dialog will appear. Select a monitor or window and click Share. If the source type does not appear, OBS was compiled without PipeWire support—use the PPA or Flatpak version.

The Flatpak of OBS always includes PipeWire support and gets portal permissions automatically:

flatpak install flathub com.obsproject.Studio

Step 6: Verify Everything Works End-to-End

Use this small test before blaming a conferencing app:

sudo apt install gstreamer1.0-pipewire   # Debian/Ubuntu
# or
sudo dnf install gstreamer1-plugin-pipewire  # Fedora

gst-launch-1.0 pipewiresrc ! videoconvert ! autovideosink

If a window appears showing your desktop, PipeWire is passing video correctly. Another quick test is the WebRTC getUserMedia test page in Firefox—request screen sharing and confirm the preview appears.

Troubleshooting

The share dialog never appears

The portal service crashed or isn't running. Check:

journalctl --user -u xdg-desktop-portal -n 50

Look for lines about missing D-Bus names or wrong backend. Restarting with systemctl --user restart xdg-desktop-portal after fixing the package issue usually resolves it.

Black screen / frozen frame in the share

This often means the compositor advertises a PipeWire node but the frame rate drops to zero after the first frame. On GNOME, disable hardware-accelerated video encoding in Settings → Privacy → Screen Sharing if present, or try toggling LIBVA_DRIVER_NAME. On Sway, set WLR_NO_HARDWARE_CURSORS=1 in your environment if the cursor itself is missing from shared output.

Only GNOME's whole-screen share works, not window share

Individual window sharing requires GNOME 43+ (using libei under the hood for some apps) and a compatible app. Most apps that use the ScreenCast portal correctly will show a window list in the picker on GNOME 43+. Older GNOME versions only offer monitor selection.

Flatpak apps can't share screen

Grant the portal permission explicitly:

flatpak permission-set screencast com.example.App yes

Or use Flatseal (available on Flathub) for a GUI interface to Flatpak permissions.