A Linux desktop application that diagnoses and fixes Wayland screen-sharing issues caused by misconfigured/mismatched PipeWire + xdg-desktop-portal + portal backends.
Portal Doctor helps investigate a common pain point for Linux desktop users: screen-sharing issues in Discord, browsers, Electron apps, OBS, Teams, Slack, and anything using the XDG Desktop Portal ScreenCast interface.
The app provides a single GUI that:
- Detects your desktop/session/portal stack configuration
- Diagnoses common failure modes with specific actionable explanations
- Offers configuration and service fixes with preview + backup + undo capabilities
- Runs a portal-based screencast test to verify real functionality
- Produces a paste-ready diagnostic report for bug trackers and support forums
- KDE Plasma (Wayland)
- GNOME (Wayland)
- Hyprland
- Sway and other wlroots-based compositors (River, Wayfire, DWL)
- COSMIC Desktop (System76)
- LXQt (Wayland)
- Cinnamon
- X11 sessions (limited functionality with appropriate warnings)
The code recognizes these environments and chooses diagnostic guidance; this list is not a tested compatibility matrix. Actual screen sharing depends on the installed portal backend, compositor and application.
- Session type detection (Wayland/X11/TTY)
- DBus session bus availability
- XDG_RUNTIME_DIR validation
- Portal service health monitoring
- Portal backend configuration verification
- PipeWire and WirePlumber status
- Socket activation detection
- GTK_USE_PORTAL environment check
- Flatpak portal access detection
- Multiple conflicting backends detection
- Overview Tab: Real-time health check with color-coded status
- Fixes Tab: One-click fixes with diff preview and undo
- Test Screencast Tab: Live XDG portal screencast testing
- Report Tab: Generate comprehensive diagnostic reports
- Menu Bar: File, View, Tools, and Help menus
- Keyboard Shortcuts: Ctrl+R (refresh), Ctrl+1-4 (tabs), F5 (test), and more
- Dark Theme: Modern, polished dark interface
portal-doctor --check # Run health check
portal-doctor --check --verbose # Detailed output with evidence
portal-doctor --check --json # JSON output for scripting
portal-doctor --report # Generate diagnostic report
portal-doctor --test-screencast # Run screencast test
portal-doctor --version # Show version- Python 3.11 or 3.12 (
>=3.11,<3.13in the package manifest) - PySide6 (Qt6)
- dbus-next, pinned to a Git revision in
pyproject.toml - A running Wayland or X11 session
- systemd user session (recommended)
# Clone the repository
git clone https://github.com/RecursiveIntell/PortalDoctor
cd PortalDoctor
# Install dependencies
poetry install
# Run the application
poetry run portal-doctor# Clone and install from source
git clone https://github.com/RecursiveIntell/PortalDoctor
cd PortalDoctor
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .
# Run
portal-doctor# Clone and run directly
git clone https://github.com/RecursiveIntell/PortalDoctor
cd PortalDoctor
./run.shThe run.sh script runs pip install --user dbus-next PySide6 when imports are missing. That path does not enforce the manifest's pinned dbus-next revision. Prefer the isolated package installation above for a reproducible dependency set.
Launch the graphical interface:
portal-doctor
# or
python -m portal_doctor| Shortcut | Action |
|---|---|
| Ctrl+R | Refresh diagnostics |
| Ctrl+S | Save report to file |
| Ctrl+Q | Quit application |
| F5 | Run screencast test |
| Ctrl+1 | Go to Overview tab |
| Ctrl+2 | Go to Fixes tab |
| Ctrl+3 | Go to Test Screencast tab |
| Ctrl+4 | Go to Report tab |
| Ctrl+/ | Show keyboard shortcuts |
# Basic health check
portal-doctor --check
# Verbose output with evidence and commands
portal-doctor --check --verbose
# JSON output for scripts/automation
portal-doctor --check --json
# Generate and save diagnostic report
portal-doctor --report
# Test screen sharing
portal-doctor --test-screencastReview the proposed action before applying it. Diagnostics normally run as your user. Configuration generation offers previews and timestamped backups, while service actions may restart PipeWire or portals and interrupt active sharing/audio sessions. Undo support for configuration files does not reverse every service or system action.
Journal-log sanitization removes selected patterns, not every possible secret or personal detail. Inspect the complete report before sharing it. Dependency installation uses the network; the app's local diagnostic workflow should not be described as a guarantee that every launcher or suggested command is offline.
# Using Poetry
poetry run pytest
# Using pytest directly
pytest tests/The project uses ruff for linting:
poetry run ruff check .
poetry run ruff format .-
"DBus session bus not available"
- Ensure you're running in a graphical session, not SSH or TTY
- Check:
echo $DBUS_SESSION_BUS_ADDRESS
-
"XDG_RUNTIME_DIR not set"
- Use a proper display manager (SDDM, GDM, LightDM)
- Don't use
startxdirectly
-
"No portal backend running"
- Install the appropriate backend for your desktop:
- KDE:
xdg-desktop-portal-kde - GNOME:
xdg-desktop-portal-gnome - Hyprland:
xdg-desktop-portal-hyprland - Sway:
xdg-desktop-portal-wlr
- KDE:
- Install the appropriate backend for your desktop:
-
"Multiple backends running"
- Create
~/.config/xdg-desktop-portal/portals.confto specify the preferred backend - Use the Fixes tab to generate the correct configuration
- Create
MIT License - See LICENSE for details.
Overview Tab showing health check status and findings
Fixes Tab providing actionable solutions with previews
Test Screencast Tab for verifying screen sharing functionality
Report Tab generating shareable diagnostic information
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Run tests (
pytest) - Submit a pull request
See CHANGELOG.md for version history.