Record your screen on Linux: X11 vs Wayland

The display server, not the distro, decides your recorder#

Search "record screen on Linux" and the top answer is almost always ffmpeg -f x11grab. Paste it into a terminal on a current Ubuntu, Fedora, or Debian desktop and you are as likely to get a black rectangle as a recording. Nothing errored, the command ran, the file just holds none of what you wanted. This is the most confusing failure in Linux screen capture, and it has one cause: the machine is running Wayland, and x11grab can only see X11.

So on Linux the first decision is not which tool but which display server you are on, because the two do not share a capture mechanism. Everything else, resolution and frame rate and the capture settings that decide sharpness, is downstream of getting a non-black frame at all. This page is a capture matrix keyed to that one axis: what works on X11, what works on Wayland, the command lines for each, and why the internet's favorite recipe went dark on you.

Check your session before you touch a recorder#

One command tells you which world you are in:

echo "$XDG_SESSION_TYPE"    # prints:  wayland   or   x11

If that variable is empty, loginctl show-session "$XDG_SESSION_ID" -p Type gives the same answer. Do this first, on any machine you did not set up yourself, because the default flipped under most people without their noticing. Wayland "is used by default in Debian 10 and newer"⁵; Fedora's GNOME has shipped Wayland by default for years, and Ubuntu's has since 21.04. The X11 answers that fill the search results were written for a default that is no longer the default. They are not wrong. They are just for the other session.

The X11 path: x11grab and anything that reads a display#

If $XDG_SESSION_TYPE says x11, the classic tooling works exactly as advertised. FFmpeg's x11grab is an "X11 video input device" that captures "a region of an X11 display"¹, reading the display named by the DISPLAY variable:

ffmpeg -f x11grab -framerate 30 -video_size 1920x1080 -i :0.0 \
       -c:v libx264 -crf 20 -pix_fmt yuv420p demo.mp4

The :0.0 is the display; the pointer is drawn by default and drops out with draw_mouse 0¹. OBS Studio's Display Capture and Window Capture sources use the same X11 access underneath and behave the same way. This path is also the one under recording a screen with no monitor attached: a virtual X server in memory is still an X server, and x11grab reads it the same as a physical one. On X11, the old recipes are still the right answer.

Why those recipes go dark under Wayland#

Wayland is not a drop-in X11. It is "a protocol between a compositor and its clients," where "the clients render locally and then communicate video memory buffers ... back to the compositor," and the architecture "integrates the display server, window manager and compositor into one process"². There is no global display object sitting in the open for any process to read. A client draws its own window and hands the pixels to the compositor; it cannot reach across and grab the whole screen, and neither can x11grab, because the X display it is pointed at is either absent or a compatibility shim (XWayland) that sees only legacy windows.

Capture on Wayland therefore goes through the compositor, by asking it. The mechanism is the org.freedesktop.portal.ScreenCast interface, a "portal for screen cast sessions" whose Start method returns "an array of PipeWire streams"³. PipeWire is the media layer that "aims to greatly improve handling of audio and video under Linux" and, "alongside Wayland and Flatpak," is meant as "a core building block for the future of Linux"⁴. The practical consequence is the one Debian spells out: "to support screenshotting, screencasting and screensharing ... pipewire is required in addition to one of the Desktop specific xdg-desktop-portal packages"⁵. Install those and the tools below work; skip them and even a Wayland-aware recorder finds nothing to record.

The Wayland path: the portal, GNOME's recorder, and the wlroots tools#

Which recorder you reach for on Wayland depends on your desktop, because the portal has per-desktop backends.

On GNOME, the fastest capture is already built in. Press Shift+Ctrl+Alt+R to start a screencast and click the red indicator to stop; the clip is "automatically saved in your Videos/Screencasts folder"⁶. No install, no portal dialog, WebM out. It is the quickest way to a clip and the least configurable.

For a produced capture on any Wayland desktop, OBS Studio is the workhorse. It "added support for Wayland on Linux" including "a new PipeWire capture source" in version 27.0⁷; pick the "Screen Capture (PipeWire)" source, approve the portal picker once, and OBS records through the compositor. Kooha is the lightweight GUI version of the same idea: it captures through PipeWire and the desktop portal and exports "WebM, MP4, GIF, and Matroska formats"⁸, handy when you want a specific container without an ffmpeg pass.

If you run a wlroots compositor — Sway, Hyprland, river — there is a scriptable, command-line option the GNOME tools do not cover. wf-recorder is "a utility program for screen recording of wlroots-based compositors"⁹, and it pairs with slurp for region selection:

wf-recorder -g "$(slurp)" --audio -f demo.mp4

The capture matrix, keyed to your display server#

Read the top of the column your session is in, and ignore the rest.

Recorder	X11	Wayland (GNOME)	Wayland (wlroots)	How it captures
ffmpeg x11grab	Yes	No (black frame)	No (black frame)	reads the X11 display directly
OBS Display Capture (X11)	Yes	No	No	X11 display access
OBS Screen Capture (PipeWire)	Yes	Yes	Yes	xdg-desktop-portal + PipeWire
GNOME built-in (Shift+Ctrl+Alt+R)	Yes (GNOME)	Yes	No	the compositor's own recorder
Kooha	portal-dependent	Yes	Yes	xdg-desktop-portal + PipeWire
wf-recorder	No	No	Yes	wlr-screencopy-v1

Two rows carry the whole lesson. x11grab is a full-height "Yes" on X11 and a full-height "No (black frame)" on Wayland, the exact trap. The PipeWire portal row is the inverse: it is the one path that spans every modern desktop, which is why OBS with the PipeWire source, or a portal-based tool like Kooha, is the safe default when you do not know or cannot control the session. Once you have a clean capture, the container and codec you save it in is a separate, portable decision that no longer cares about the display server.

When the cleanest answer is no display to fight over#

There is a way to sidestep the X11-versus-Wayland question: do not record a desktop at all. A browser can hand you its own frames with no display server in the loop, which is why the same web demo records identically on a laptop, a headless container, and a CI runner, and why capturing a screen that was never painted to a monitor is its own technique. In-browser, getDisplayMedia() asks "the user to select a screen or portion of a screen to capture" and needs a recent user gesture to fire¹⁰; it works across sessions but is interactive, so it fits capturing one browser tab by hand more than an automated pipeline.

This is the lane our own tool sits in. aidemo, which we build, drives a real Chrome and pulls frames from the browser rather than the desktop, so a demo renders the same whether the box runs X11, Wayland, or no display server at all, and the whole matrix above becomes moot. The honest limits: it records a browser only, so a native Linux app is squarely a case for x11grab or the PipeWire portal, not for us; you (or an agent) write its storyboard in code rather than dragging clips on a GUI timeline; and there is no click-to-trim editor. For a terminal session specifically, a text-based recording beats a video entirely.

Sources#

FAQ#

How do I record my screen on Ubuntu?#

Ubuntu has defaulted to a Wayland session since 21.04, so run echo "$XDG_SESSION_TYPE" first: if it prints wayland, an old ffmpeg x11grab command will capture a black frame. Use OBS Studio's "Screen Capture (PipeWire)" source, the lightweight Kooha app, or GNOME's built-in recorder (Shift+Ctrl+Alt+R) instead, and make sure the pipewire and xdg-desktop-portal packages are installed. If the variable prints x11, the classic x11grab and OBS Display Capture recipes work unchanged.

Why does my screen recorder capture a black screen on Wayland?#

Because it is an X11 tool pointed at a display Wayland does not expose. Wayland folds the display server, window manager, and compositor into one process and gives no client global access to the screen, so anything built on X11 screen grabbing — x11grab, older OBS capture, many legacy recorders — sees nothing or only XWayland windows. The fix is a recorder that goes through the xdg-desktop-portal ScreenCast interface and PipeWire, which asks the compositor for the frames instead of trying to read them directly.

What is the keyboard shortcut to record the screen in GNOME?#

Shift+Ctrl+Alt+R starts and stops a screencast on GNOME, on both its Wayland and X11 sessions, and a red indicator in the top bar shows the recording is live. The clip lands in your Videos/Screencasts folder as a WebM file. It is the fastest route to a quick recording; for zoom, cursor smoothing, or captions you will want a produced recorder or a compose step on top.

This article was researched and drafted with AI assistance and reviewed by the aidemo maintainers. Tool capabilities and prices change — check vendor docs before deciding. How we research and correct our articles →