Screenshare Doctor

Find out why screen sharing fails on your Linux Wayland desktop.

Status: 0.1.0 is the first release, tested on real GNOME, KDE Plasma and Hyprland sessions. Reports from other setups are very welcome; see the roadmap for what comes next.

You click "Share screen" in a browser or a meeting app and get a black frame, no picker, the wrong windows or a permission error. The cause can sit in the app, the way it was launched (native, Flatpak, XWayland), the xdg-desktop-portal routing, the desktop's portal backend, PipeWire, WirePlumber or the compositor. Screenshare Doctor starts from the app and the symptom and tells you which layer is most likely at fault, with the evidence:

Install

Needs Python 3.11 or newer and a Linux desktop session to diagnose.

uv tool install git+https://github.com/BhuwanJoshi-01/screenshare-doctor   # until the PyPI release
pipx install git+https://github.com/BhuwanJoshi-01/screenshare-doctor      # or with pipx

Use

screenshare-doctor troubleshoot screenshare --app firefox --symptom no-picker
screenshare-doctor routes explain ScreenCast     # which portal backend handles screen sharing, and why
screenshare-doctor report --output screenshare-report.md   # redacted, safe to paste

It is tested on real GNOME, KDE Plasma and Hyprland sessions. A desktop is listed as supported only after such a test.

What works already (see the command reference):

• screenshare-doctor troubleshoot screenshare --app firefox --symptom no-picker starts from the app and what you see, and shows the checks that explain it, most likely cause first (apps and symptoms).
• screenshare-doctor doctor runs every check, from the session to PipeWire, and explains what needs attention; --format json for scripts (JSON output).
• screenshare-doctor report --output screenshare-report.md writes a redacted report to paste into a bug tracker.
• screenshare-doctor check session tells Wayland, X11, SSH and no session apart and shows the desktop names the portal reads.
• screenshare-doctor check services shows which portal backends, PipeWire and WirePlumber are installed and running, and whether portals will see the same desktop variables as your shell.
• screenshare-doctor check dbus shows which portal services are on the session bus and what they offer for screen sharing, without starting any of them.
• screenshare-doctor check desktop compares your setup with what GNOME, KDE Plasma, Hyprland or wlroots ship by default (the defaults and their sources).
• screenshare-doctor routes explain ScreenCast names the backend the portal picks, the line of the portals.conf that decides it, and whether the bus agrees, using the rules of your portal version (how routing works).

What it promises

• Passive by default. No command opens a screen-sharing request or picker, records anything, starts, restarts or stops a service, or changes configuration. A portal that isn't running is reported as such, not started. Testing a real screen-sharing request (planned for 0.2) is a separate command that asks first.
• No root. It never needs sudo.
• Configured vs observed. The report says whether a backend is predicted by your portals.conf files or observed answering on D-Bus.
• Unknown is not a pass. A check that could not run is shown as unknown, never as green.
• Shareable reports. User names, home paths and window titles are redacted before any output is written, JSON included. No network access, no telemetry.

GNOME Shell extension

A small top-bar indicator shows the result of doctor whenever you open its menu; see extension/README.md. It needs the command-line tool and runs nothing while the menu is closed.

Tested on

Real Wayland sessions of GNOME 50.1 (Ubuntu 26.04), KDE Plasma 6.8.2 (Fedora 45, in a VM) and Hyprland 0.57.1 (Arch Linux, in a VM). wlroots compositors such as sway are covered by upstream defaults only. See the support matrix and privacy.

Alternatives

• PortalDoctor offers thorough read-only portal, D-Bus and PipeWire diagnostics, validated on GNOME.
• wayland-cast-doctor checks the session, the ScreenCast backend and PipeWire.

Screenshare Doctor focuses on the app-centred workflow and on validated GNOME, KDE and Hyprland coverage.

Documentation

Command reference · Troubleshooting · Checks · Portal routing · Desktop defaults · Apps and symptoms · Privacy · Support matrix · JSON output · Architecture · Sample reports · Roadmap

License

The CLI is MIT. The GNOME Shell extension is GPL-2.0-or-later.