Configuration Overview
Here are all of these options at a glance:Startup Programs
spawn-at-startup
Spawn processes at niri startup. Accepts a path to the program binary as the first argument, followed by arguments to the program.
Running niri as a systemd session supports xdg-desktop-autostart out of the box, which may be more convenient to use. Apps that you configured to autostart in GNOME will also “just work” in niri, without any manual
spawn-at-startup configuration.spawn-sh-at-startup
Available since version 25.08
Run shell commands at niri startup. The argument is a single string that is passed verbatim to
sh. You can use shell variables, pipelines, ~ expansion and everything else as expected.Window Decorations
prefer-no-csd
Ask applications to omit their client-side decorations. If an application will specifically ask for CSD, the request will be honored. Additionally, clients will be informed that they are tiled, removing some rounded corners.
prefer-no-csd set, applications that negotiate server-side decorations through the xdg-decoration protocol will have focus ring and border drawn around them without a solid colored background.
Unlike most other options, changing
prefer-no-csd will not entirely affect already running applications. It will make some windows rectangular, but won’t remove the title bars. This mainly has to do with niri working around a bug in SDL2 that prevents SDL2 applications from starting.Restart applications after changing prefer-no-csd in the config to fully apply it.Screenshots
screenshot-path
Set the path where screenshots are saved. A
~ at the front will be expanded to the home directory. The path is formatted with strftime(3) to give you the screenshot date and time.null to disable saving screenshots to disk:
Environment Variables
environment
Override environment variables for processes spawned by niri. Set a variable to
null to remove it.Cursor Settings
cursor
Change the theme and size of the cursor as well as set the
XCURSOR_THEME and XCURSOR_SIZE environment variables.hide-when-typing
Available since version 0.1.10
If set, hides the cursor when pressing a key on the keyboard.
This setting might interfere with games running in Wine in native Wayland mode that use mouselook, such as first-person games. If your character’s point of view jumps down when you press a key and move the mouse simultaneously, try disabling this setting.
hide-after-inactive-ms
Available since version 0.1.10
If set, the cursor will automatically hide once this number of milliseconds passes since the last cursor movement.
Overview Settings
Available since version 25.05
Settings for the Overview feature.
zoom
Control how much the workspaces zoom out in the overview. Ranges from 0 to 0.75 where lower values make everything smaller.
backdrop-color
Set the backdrop color behind workspaces in the overview. The backdrop is also visible between workspaces when switching. The alpha channel for this color will be ignored.
workspace-shadow
Control the shadow behind workspaces visible in the overview. Settings mirror the normal shadow config in the layout section.
Xwayland Integration
Available since version 25.08
xwayland-satellite
Settings for integration with xwayland-satellite.
DISPLAY, then automatically spawn xwayland-satellite when an X11 client tries to connect. If Xwayland dies, niri will keep watching the X11 socket and restart xwayland-satellite as needed. This is very similar to how built-in Xwayland works in other compositors.
off disables the integration: niri won’t create an X11 socket and won’t set the DISPLAY environment variable.
path sets the path to the xwayland-satellite binary. By default, it’s just xwayland-satellite, so it’s looked up like any other non-absolute program name.
Clipboard Settings
Available since version 25.02
clipboard
Clipboard settings.
disable-primary flag to disable the primary clipboard (middle-click paste). Toggling this flag will only apply to applications started afterward.
Hotkey Overlay
hotkey-overlay
Settings for the “Important Hotkeys” overlay.
skip-at-startup
Set this flag if you don’t want to see the hotkey help at niri startup.
hide-not-bound
Available since version 25.08
By default, niri will show the most important actions even if they aren’t bound to any key, to prevent confusion. Set this flag if you want to hide all actions not bound to any key.
Config Notification
Available since version 25.08
config-notification
Settings for the config created/failed notification.
disable-failed flag to disable the “Failed to parse the config file” notification. For example, if you have a custom one.