Skip to main content
Frequently asked questions about niri configuration, features, and usage.

​
Window Appearance

Uncomment the prefer-no-csd setting at the top level of your config, then restart your apps:
prefer-no-csd
Niri will ask windows to omit client-side decorations and inform them that they are being tiled (which makes some windows rectangular, even if they cannot omit the decorations).
This will currently prevent edge window resize handles from showing up. You can still resize windows by holding Mod and the right mouse button.
Uncomment the prefer-no-csd setting at the top level of your config, then restart your apps:
prefer-no-csd
Niri will draw focus rings and borders around windows that agree to omit their client-side decorations.By default, focus ring and border are rendered as a solid background rectangle behind windows. They will show up through semitransparent windows because windows using client-side decorations can have an arbitrary shape.You can also override this behavior with the draw-border-with-background window rule.
Add this window rule to your config:
window-rule {
    geometry-corner-radius 12
    clip-to-geometry true
}
Adjust the radius value to your preference.
They draw their own 1 px dark border around the window, which obscures one pixel of niri’s border.Solution: Set the clip-to-geometry true window rule:
window-rule {
    match app-id="firefox"
    clip-to-geometry true
}

​
User Interface

Add this to your config:
hotkey-overlay {
    skip-at-startup
}

​
X11 and Xwayland

To run X11 apps, use xwayland-satellite. Check the Xwayland documentation page for detailed instructions.
Many Electron apps such as VSCode or Discord can run natively on Wayland by passing the right flags. See the Application Issues page for details.
A combination of factors:
  • Integrating Xwayland is quite a bit of work, as the compositor needs to implement parts of an X11 window manager
  • You need to appease X11 ideas of windowing, whereas niri aims to have the best code for Wayland
  • Niri doesn’t have a good global coordinate system required by X11
  • X11 tends to generate an endless stream of bugs that take time away from other tasks
  • There aren’t actually that many X11-only clients nowadays, and xwayland-satellite handles most of those well
  • Niri isn’t a Big Serious Desktop Environment which Must Support All Use Cases
Since version 25.08, niri has seamless built-in xwayland-satellite integration that works as well as built-in Xwayland in other compositors, solving the hurdle of manual setup.
It’s possible that xwayland-satellite may become the standard way of integrating Xwayland into new compositors, since it takes on the bulk of the annoying work and isolates the compositor from misbehaving clients.

​
Features and Effects

Not yet in the stable release. Follow/upvote this issue for progress.There’s also a PR adding blur to niri which you can build and run manually.
The PR is an experimental implementation that may have problems and performance concerns.
Not yet in the stable release. Follow/upvote this issue for progress.You can emulate this with a script that uses the niri IPC. For example, nirius has a toggle-follow-mode feature.

​
Window Placement

Firefox first opens the Bitwarden window with a generic Firefox title, and only later changes it to Bitwarden, so you can’t effectively target it with an open-floating window rule.Solution: Use a script, for example this one. Search niri issues and discussions for other Bitwarden solutions.
Not built into niri directly, but you can script this behavior with the niri IPC.Listen to the event stream for a new window opening, then call an action like consume-or-expel-window-left.Adding this directly to niri is challenging:
  • Computing exact initial window sizes in relation to other windows in a column is complex
  • Edge cases need handling (column disappearing, new windows added before target window appears)
  • It’s unclear what kind of simple setting would be useful for different user needs (parent PID rules, etc.)
See also this discussion for more context.

​
Input and Focus

This can happen with focus-follows-mouse. When using client-side decorations, windows have margins outside their geometry for mouse resizing handles. These margins “peek out” of the monitor edges and trigger focus-follows-mouse when the mouse crosses them.Why it doesn’t always happen:
  • Some toolkits don’t put resize handles outside the window geometry
  • If the current window has its own margin extending to the monitor edge, the mouse never leaves the current window
Solutions:Option 1: Prevent scrolling-triggered focus changes:
focus-follows-mouse max-scroll-amount="0%"
Option 2: Remove resizing margins:
prefer-no-csd

​
Screen Locking

When your screen locker dies, you’ll see a red screen (niri’s locked session background).Recovery Method 1: Switch TTY and spawn a new locker
  1. Press Ctrl+Alt+F3 to switch to a different TTY
  2. Spawn a screen locker to niri’s Wayland display: 
    WAYLAND_DISPLAY=wayland-1 swaylock
Recovery Method 2: Allow locker binding when lockedSet allow-when-locked=true on your screen locker bind:
binds {
    Super+Alt+L allow-when-locked=true { spawn "swaylock"; }
}
Then you can press the keybinding on the red screen to spawn a fresh screen locker.

​
Output Configuration

If you need different output configurations depending on what outputs are connected, use Kanshi.Kanshi has its own simple configuration and communicates with niri via IPC.Setup:
  1. Launch Kanshi from your niri config: 
    spawn-at-startup "/usr/bin/kanshi"
  2. Create a Kanshi config. Example for scaling laptop display differently when external monitor is connected: 
    profile {
    output eDP-1 enable scale 1.0
}

profile { 
    output HDMI-A-1 enable scale 1.0 position 0,0
    output eDP-1 enable scale 1.25 position 1920,0
}

Build docs developers (and LLMs) love

Get started for freeTalk to us