Fix a Black Screen in OBS Studio on Ubuntu

A black rectangle in OBS feels like one problem, but it can be produced by several very different failures. Sometimes OBS captured the wrong display protocol. Sometimes the portal request was cancelled, the source is hidden behind another layer, or a window stopped matching after its title changed. The fastest fix is to identify which layer failed before changing the desktop session.

First identify what is actually black

• Only one source is black: its capture method, target window, permission, or transform is the likely fault.

• Every source and the OBS interface are black or corrupted: investigate graphics drivers, rendering, package integrity, and the GPU running OBS.

• Preview works but the saved file is black: inspect the recorded file in another player, output settings, encoder errors, and the OBS log.

• Preview is black but the pointer moves: the cursor and desktop pixels are arriving through different paths; a mismatched display-capture source is especially likely.

Confirm the Ubuntu session and OBS package

$ printf 'Session: %s\nDesktop: %s\n' "$XDG_SESSION_TYPE" "$XDG_CURRENT_DESKTOP"
obs --version
apt-cache policy obs-studio

How these results narrow the fault

• XDG_SESSION_TYPE should normally be wayland or x11; choose capture sources for that protocol.

• obs --version establishes the build under test and exposes an unexpected launcher or stale installation.

• apt-cache policy is read-only and shows an APT installation’s origin; it may show nothing installed when OBS came from Flatpak or another package model.

• Record the session, desktop, OBS version, and packaging method before comparing symptoms with another machine.

Wayland: rebuild capture through PipeWire

Wayland intentionally prevents applications from reading the desktop without mediation. OBS requests a screen or window through the desktop portal, and PipeWire carries the selected frames. An X11 capture source inside a Wayland session is therefore the wrong first tool.

1. In Sources, remove or disable the failed legacy display source so you can test cleanly.

1. Add Screen Capture (PipeWire). For one application, use Window Capture (PipeWire) when the installed OBS build offers it.

1. When Ubuntu’s sharing dialog appears, select the intended monitor or window and approve the request. Cancelling or denying it leaves OBS without the requested stream.

1. Bring the new source to the top, ensure its eye icon is enabled, and choose Transform → Fit to Screen.

1. Move a visible window on the selected display and make a short recording; do not judge from a static wallpaper alone.

Check PipeWire and the portal without restarting them

$ systemctl --user --no-pager --full status pipewire.service xdg-desktop-portal.service
systemctl --user --no-pager --failed

What service status can and cannot prove

• systemctl --user queries services belonging to the current login session; no system-wide privilege is required.

• An active PipeWire service and portal are necessary context, but do not prove the correct desktop-specific portal backend handled the request.

• A missing generic service name, a failed backend, or a portal error should be resolved through Ubuntu package and session diagnostics rather than random permission changes.

• Do not launch OBS with sudo; a root process uses the wrong desktop session context and expands security risk.

X11: use a source that can see X11 content

• Use the available X11 screen-capture source for a full display and Window Capture (Xcomposite) for one application.

• Open the source properties and reselect the target window; strict title matching can break after an application changes its title.

• If a minimized application stops rendering, restore it and retest. Some applications do not continually paint an obscured or minimized window.

• Test an ordinary terminal or text editor. If it works while one accelerated application stays black, the fault is application-specific rather than global display capture.

Rule out a scene-layout mistake

1. Confirm the source eye icon is visible and that you are editing the same scene shown in Preview.

1. Drag the capture source above opaque color, image, browser, or media sources.

1. Select the source and use Transform → Reset Transform, followed by Fit to Screen.

1. Check that crop values are not hiding the whole source and that its opacity filter is not zero.

1. Create a temporary empty scene with only one new capture source. If that works, the original scene—not Ubuntu capture—is the problem.

Inspect the log from a session that reproduced the failure

Restart OBS, recreate the black source, leave it visible briefly, then choose Help → Log Files → Upload Current Log File. OBS support guidance stresses reproducing the problem in the same session; a clean log from another launch has little diagnostic value.

Look for evidence, not a favourite error string

• Confirm the log’s session type, OBS version, renderer, GPU, loaded modules, and the source added during the reproduction.

• Portal cancellation or denial points back to the Wayland sharing prompt; plugin load failures point to package or ABI mismatch.

• Rendering errors affect scene composition, while encoder errors more often explain a bad output file after a healthy preview.

• Use the OBS log analyser as a lead generator, then validate each suggestion against the actual source and system.

Multi-GPU laptops need one more controlled test

Hybrid-graphics systems can put the desktop, captured application, and OBS on different GPUs. Current capture paths handle more of these combinations than old releases, but a driver or compositor boundary can still matter. First update OBS through its existing package source and install supported Ubuntu graphics drivers; then compare a simple desktop source with the problematic accelerated application.

• Avoid copying Windows-only “run as administrator” or Graphics Settings fixes into Ubuntu.

• Do not force environment variables or discrete-GPU launchers until the OBS log identifies the renderer and the controlled source test suggests a GPU boundary.

• If changing the GPU launch path makes one capture work but breaks hardware encoding, record both results; that tradeoff reveals where frames cross devices.

• Prefer distribution-supported driver changes over downloading an arbitrary installer from a search result.

When restarting portal services is reasonable

A portal can become stuck after a desktop update or interrupted sharing request. Save work and log out and back in first; that creates a clean user session. Restarting user portal services manually can terminate active screen shares and file-picker sessions, so it is a troubleshooting action—not routine setup.

$ systemctl --user restart xdg-desktop-portal.service
systemctl --user --no-pager --full status xdg-desktop-portal.service

What this restart changes

• restart stops and starts the current user’s generic portal service; existing portal-mediated operations may be interrupted.

• The command does not install a missing GNOME or KDE portal backend and does not repair mismatched packages.

• After the restart, delete and recreate the PipeWire capture source so OBS issues a new portal request.

• If the service fails again, collect its journal and diagnose the desktop-specific backend instead of repeating restarts.

Disabling Wayland is a last-resort comparison, not the fix

The original article edited /etc/gdm3/custom.conf and set WaylandEnable=false. That changes the login manager for every user and discards Wayland’s capture security model. A safer comparison is to log out, choose an Ubuntu on Xorg session from the login screen when that option exists, and test OBS once. If X11 works, you have useful evidence about the portal or Wayland capture path; you have not proved Wayland must remain disabled.

Verification checklist

• The preview shows motion from the specifically selected monitor or application.

• The source survives switching scenes and reopening its properties.

• A 30-second recording contains the same picture seen in Preview.

• View → Stats shows no unexplained rendering or encoding failure during the test.

• The current OBS log records the expected session, source type, renderer, and no repeated capture error.

• The solution still works after restarting OBS without running it as root or weakening desktop-wide security.

Related OBS resources

• Set up OBS Studio on Ubuntu and verify a complete recording.

• Install OBS Studio on Ubuntu from a maintainable package source.

• OBS Window Capture source documentation.

• OBS guidance for capturing a useful diagnostic log.