Screen capture on Wayland works. It works differently from X11, and the transition broke a decade of tools and tutorials, which is why searching for help produces so much outdated advice.

Why the old tools stopped working

Under X11, any client connected to the display server can read the entire screen, including other applications’ windows and their keystrokes. scrot works by asking X for the root window’s contents, and X hands them over without asking anyone.

That is an appalling security property. It means any application you run, including one you installed carelessly, can silently watch everything you do. It is also what made screenshot tools trivial to write.

Wayland closed it deliberately. A Wayland client can see its own surfaces and nothing else. There is no protocol for “give me the screen” available to arbitrary clients.

So capture had to be rebuilt around explicit permission, and the mechanism is portals.

How it works now

xdg-desktop-portal is a D-Bus service that acts as a trusted intermediary. An application asks the portal for screen capture. The portal, which runs outside any sandbox, asks you. If you agree, it hands the application a PipeWire stream of the selected screen or window.

The application never gets general screen access. It gets one stream, because you approved it.

This requires a backend matching your compositor:

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

Desktop	Package
GNOME	xdg-desktop-portal-gnome
KDE Plasma	xdg-desktop-portal-kde
Sway, Hyprland, wlroots	xdg-desktop-portal-wlr
COSMIC	xdg-desktop-portal-cosmic

A missing or mismatched backend is the single most common cause of “screen recording is broken on Linux”. The symptom is that nothing happens, or a permission dialog never appears, or you get a black frame.

# is the service running
systemctl --user status xdg-desktop-portal

# which backend got selected
journalctl --user -u xdg-desktop-portal --since "10 minutes ago"

Having two backends installed can also cause trouble, because the wrong one gets chosen. If you switched desktops, remove the one you no longer use.

Screenshots

wlroots compositors: Sway, Hyprland, river

grim and slurp are the primitives.

sudo apt install grim slurp wl-clipboard

# whole screen
grim ~/screenshot.png

# select a region
grim -g "$(slurp)" ~/region.png

# region straight to clipboard
grim -g "$(slurp)" - | wl-copy

# one output
grim -o DP-1 ~/monitor.png

slurp lets you drag a rectangle and prints its geometry; grim captures it. Composing them is the whole design.

grimblast wraps both with nicer defaults and is what most Hyprland configurations use.

These rely on the wlr-screencopy protocol, which GNOME and KDE do not implement. grim will not work there, and that is not a bug in grim.

GNOME

The built-in tool covers most needs. PrtSc opens an interface for area, window, or screen, with a screen recording toggle.

For scripting, GNOME exposes a D-Bus interface:

gdbus call --session \
  --dest org.gnome.Shell.Screenshot \
  --object-path /org/gnome/Shell/Screenshot \
  --method org.gnome.Shell.Screenshot.Screenshot \
  true false "/home/user/shot.png"

KDE Plasma

Spectacle is genuinely good and has a complete command-line interface:

spectacle -b -r -o ~/region.png     # background, region, output file
spectacle -b -a -o ~/active.png     # active window
spectacle -b -f -o ~/full.png       # fullscreen

Anywhere: Flameshot

Flameshot has Wayland support through portals in current versions, and its annotation tools are the reason to use it: arrows, boxes, blur, and text drawn on the screenshot immediately after capture.

flameshot gui

Older builds predate portal support and will not work. Check the version if it fails.

Screen recording

OBS Studio

The serious option, and it works well on Wayland once configured correctly.

The critical step: use the PipeWire source, not X11. Add a source, choose Screen Capture (PipeWire), and a portal dialog appears asking which screen or window to share.

flatpak install flathub com.obsproject.Studio

The Flatpak build bundles what it needs and is the easier path. It requires a working portal backend like everything else.

If OBS shows a black screen, the cause is almost always one of: the X11 source selected instead of PipeWire, a missing portal backend, or OBS running under XWayland.

wf-recorder

Minimal, for wlroots compositors:

wf-recorder -f recording.mp4
wf-recorder -g "$(slurp)" -f region.mp4
wf-recorder -c h264_vaapi -d /dev/dri/renderD128 -f hw.mp4

That last one uses VAAPI hardware encoding, which drops CPU usage substantially on a long recording.

GNOME built-in

Ctrl+Alt+Shift+R starts and stops recording. No configuration, no options, and it writes a WebM to ~/Videos. For a quick demonstration it is the fastest route available.

Kooha and GPU Screen Recorder

Kooha is a simple GTK recorder using portals and PipeWire, and it works across desktops.

GPU Screen Recorder is worth knowing about for gaming. It uses hardware encoding with very low overhead and supports replay buffer, which continuously records the last N seconds so you can save something after it happened. Our gaming on Linux guide covers the wider picture.

Troubleshooting

Nothing happens at all. Missing portal backend. Install the one matching your compositor and restart the portal service:

systemctl --user restart xdg-desktop-portal xdg-desktop-portal-gnome

Black screen in the recording. The application is capturing via X11 or running under XWayland. Check:

echo $XDG_SESSION_TYPE       # should print wayland

For OBS specifically, confirm the source type is PipeWire.

Old tool does not work. scrot, import from ImageMagick, xwd, and older Flameshot builds are X11-only. They will capture XWayland windows and nothing else, which produces confusingly partial results.

Permission prompt every time. This is the design. Some backends offer to remember the choice per application or per session.

Cursor missing or duplicated. Most tools have a flag: grim -c includes the cursor, wf-recorder has -C. Duplication usually means the cursor is being composited twice, once by the compositor and once by the tool.

The tradeoff, honestly

The Wayland model is more secure and less convenient. A permission dialog before every capture is friction that X11 did not have, and the reason X11 did not have it is that it granted the access unconditionally to everything.

The transitional pain has been real. A great deal of tooling assumed X11 semantics, and rebuilding it has taken years. That work is now largely done, and every actively maintained capture tool supports the portal path.

If something does not work, check the portal backend first. It is the answer far more often than anything else.

Frequently Asked Questions

Why does my screenshot tool not work on Wayland?

Wayland does not let an application read the screen directly, which X11 allowed. Tools written against X11 such as scrot and older Flameshot builds have no way to capture anything. Capture now goes through the xdg-desktop-portal service, so the tool must support portals or use a compositor-specific protocol.

What is xdg-desktop-portal and why do I need it?

It is a D-Bus service that lets sandboxed and unprivileged applications request things outside their reach, including screen capture. A backend matching your desktop must be installed, such as xdg-desktop-portal-gnome, -kde, or -wlr, and a missing backend is the most common reason capture silently fails.

Why does OBS show a black screen on Wayland?

Usually because it is using the X11 capture source rather than PipeWire. Switch the source to Screen Capture with PipeWire and make sure OBS was built with PipeWire support. A missing or mismatched portal backend for your desktop produces the same symptom.

How do I take a screenshot from the command line on Wayland?

On wlroots compositors such as Sway and Hyprland, use grim, optionally piped with slurp for region selection. On GNOME and KDE, use the desktop tools or grimblast and spectacle respectively, since those compositors do not implement the wlroots screencopy protocol that grim needs.

Can I record my screen without a desktop environment?

Yes. wf-recorder works on wlroots compositors and writes directly to a video file, and OBS works anywhere PipeWire and a portal backend are present. Both need the compositor to support screen capture, which every actively maintained one does.

Why does a permission dialog appear every time I record?

The portal asks for consent because the application is requesting access to your screen contents, which is sensitive. Some portal backends offer to remember the choice for a session or for a specific application, and the prompt is the security property working rather than a bug.