Skip to main content

​
Using xwayland-satellite

Available since version 25.08
Niri integrates with xwayland-satellite out of the box.

​
Automatic Integration

With no configuration, niri will:
  1. Create X11 sockets on disk
  2. Export $DISPLAY
  3. Spawn xwayland-satellite on-demand when an X11 client connects
  4. Automatically restart xwayland-satellite if it dies
1

Install xwayland-satellite

Ensure xwayland-satellite >= 0.7 is installed and available in $PATH.
2

Remove Custom Config

If you had a custom config which manually started xwayland-satellite and set $DISPLAY, you should remove those customizations for the automatic integration to work.
3

Verify Integration

Check that niri is listening on the X11 socket:
journalctl --user-unit=niri -b
You should see:
niri[2474]: 2025-08-29T04:07:40.690512Z  INFO niri: listening on Wayland socket: wayland-1
niri[2474]: 2025-08-29T04:07:40.690520Z  INFO niri: IPC listening on: /run/user/1000/niri.wayland-1.2474.sock
niri[2474]: 2025-08-29T04:07:40.700137Z  INFO niri: listening on X11 socket: :0
Verify $DISPLAY is set:
echo $DISPLAY
# Output: :0
xwayland-satellite running Steam and Half-Life

​
Why xwayland-satellite?

We’re using xwayland-satellite rather than Xwayland directly because X11 is very cursed. xwayland-satellite takes on the bulk of the work dealing with the X11 peculiarities from us, giving niri normal Wayland windows to manage.
xwayland-satellite works well with most applications (Steam, games, Discord, even wine Windows VST plugins), but X11 apps that want to position windows or bars at specific screen coordinates won’t behave correctly and will need a nested compositor to run.

​
Using the labwc Wayland Compositor

Labwc is a traditional stacking Wayland compositor with Xwayland. You can run it as a window, then run X11 apps inside.
1

Install labwc

Install labwc from your distribution packages.
2

Run labwc

Run it inside niri with the labwc command. It will open as a new window.
labwc
3

Run X11 Applications

Run an X11 application on the X11 DISPLAY that it provides:
env DISPLAY=:0 glxgears
Labwc running X11 apps

​
Directly Running Xwayland in Rootful Mode

This method involves invoking Xwayland directly and running it as its own window. It also requires an extra X11 window manager running inside it. Xwayland running in rootful mode
1

Start Xwayland

Run Xwayland (just the binary on its own without flags):
Xwayland
This will spawn a black window which you can resize and fullscreen (with Mod+Shift+F).
On older Xwayland versions the window will be screen-sized and non-resizable.
2

Run X11 Window Manager

Run an X11 window manager inside Xwayland:
env DISPLAY=:0 i3
This way you can manage X11 windows inside the Xwayland instance.
3

Run X11 Applications

Run your X11 applications:
env DISPLAY=:0 flatpak run com.valvesoftware.Steam
If you don’t run an X11 window manager, Xwayland will close and re-open its window every time all X11 windows close and a new one opens. To prevent this, start an X11 WM inside as mentioned above, or open some other long-running X11 window.

​
Clipboard Sharing

Currently rootful Xwayland doesn’t seem to share clipboard with the compositor.
For textual data you can do it manually using wl-clipboard: 
# Copy from Xwayland to niri clipboard
env DISPLAY=:0 xsel -ob | wl-copy

# Copy from niri to Xwayland clipboard
wl-paste -n | env DISPLAY=:0 xsel -ib

​
Hotkey Bindings

You can bind these to hotkeys: 
binds {
    Mod+Shift+C { spawn "sh" "-c" "env DISPLAY=:0 xsel -ob | wl-copy"; }
    Mod+Shift+V { spawn "sh" "-c" "wl-paste -n | env DISPLAY=:0 xsel -ib"; }
}

​
Using xwayland-run

xwayland-run is a helper utility to run an X11 client within a dedicated Xwayland rootful server. It takes care of starting Xwayland, setting the X11 DISPLAY environment variable, setting up xauth and running the specified X11 client. When the X11 client terminates, xwayland-run will automatically close the dedicated Xwayland server.

​
Usage

xwayland-run <Xwayland arguments> -- your-x11-app <X11 app arguments>

​
Example

xwayland-run -geometry 800x600 -fullscreen -- wine wingame.exe

​
Using the Cage Wayland Compositor

It is also possible to run the X11 application in Cage, which runs a nested Wayland session which also supports Xwayland.
Cage is meant for kiosks, so every new window will be automatically full-screened and take over the previously opened window. This can cause issues if multiple windows are launched inside Cage.

​
Setup

1

Install Cage

Install cage from your distribution repositories:
# Most distributions have cage in their repos
sudo dnf install cage  # Fedora
sudo apt install cage  # Debian/Ubuntu
2

Run Application

Run your X11 application with Cage:
cage -- /path/to/application

​
Desktop Entry Modification

Optionally, you can modify the desktop entry for the application and add the cage -- prefix to the Exec property. For example, the Spotify Flatpak would look like: 
[Desktop Entry]
Type=Application
Name=Spotify
GenericName=Online music streaming service
Comment=Access all of your favorite music
Icon=com.spotify.Client
Exec=cage -- flatpak run com.spotify.Client
Terminal=false

​
Proton-GE Native Wayland

It’s possible to run some games as native Wayland clients, sidestepping the issues related to X11. You can do it with a custom version of Proton like Proton-GE by setting the PROTON_ENABLE_WAYLAND=1 environmental variable in the game’s launch parameters.
This is an experimental feature, might not work with every game and might have its own issues.

​
Steam Launch Options

PROTON_ENABLE_WAYLAND=1 %command%

​
Using gamescope

You can use gamescope to run X11 games and even Steam itself.
Similar to Cage, gamescope will only show a single, topmost window, so it’s not very suitable for running regular apps. But you can run Steam in gamescope and then start games from Steam just fine.

​
Basic Usage

gamescope -- flatpak run com.valvesoftware.Steam

​
Fullscreen Mode

To run gamescope fullscreen, pass flags that set the necessary resolution: 
gamescope -W 2560 -H 1440 -w 2560 -h 1440 -f -- flatpak run com.valvesoftware.Steam
If Steam terminates abnormally while running in gamescope, subsequent gamescope invocations will sometimes fail to start it properly. If this happens, run Steam inside a rootful Xwayland as described above, then exit it normally, and then you will be able to use gamescope again.

Build docs developers (and LLMs) love

Get started for freeTalk to us