Skip to main content
This guide will help you install niri and get it running on your system. Choose between a quick start with DankMaterialShell for an out-of-the-box experience, or a manual installation for more control.

​
Quick Start with DankMaterialShell

For the easiest setup experience, install niri with DankMaterialShell, which provides a complete desktop environment including panels, notifications, and system controls. 
sudo dnf copr enable avengemedia/dms
sudo dnf install niri dms
systemctl --user add-wants niri.service dms
1

Install packages

Run the commands above for your distribution to install niri and DankMaterialShell.
2

Log out and select Niri

Log out of your current session, select “Niri” in your display manager, and log back in.If not using a display manager, run niri-session on a TTY.
3

Fix dual bar issue (if applicable)

The default niri config runs Waybar, which may conflict with DMS. If you see two bars:
pkill waybar
Then open ~/.config/niri/config.kdl and remove the spawn-at-startup "waybar" line.
Check the DankMaterialShell’s compositor setup page to learn how to configure DMS-specific binds and niri integrations.

​
Manual Installation

For more control over your setup, you can install niri from distribution packages or build it yourself.

​
Distribution Packages

niri is available in several package repositories:
After installing from your distribution, continue to the First Launch section.

​
Building from Source

To build niri yourself, you’ll need Rust and various system dependencies.
1

Install dependencies

sudo apt-get install -y gcc clang libudev-dev libgbm-dev libxkbcommon-dev \
  libegl1-mesa-dev libwayland-dev libinput-dev libdbus-1-dev libsystemd-dev \
  libseat-dev libpipewire-0.3-dev libpango1.0-dev libdisplay-info-dev
2

Install Rust

Install the latest stable Rust from rustup.rs:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
3

Build niri

cargo build --release
Do NOT build with --all-features! Some features are meant only for development and may cause issues like unbounded memory growth.
For alternative init systems, use:
cargo build --release --no-default-features --features dinit,dbus,xdp-gnome-screencast
4

Install files manually

Copy the built files to their destinations:
FileDestination
target/release/niri/usr/local/bin/
resources/niri-session/usr/local/bin/
resources/niri.desktop/usr/local/share/wayland-sessions/
resources/niri-portals.conf/usr/local/share/xdg-desktop-portal/
resources/niri.service/etc/systemd/user/
resources/niri-shutdown.target/etc/systemd/user/
Make sure the path to niri in niri.service matches your installation location (defaults to /usr/bin/niri).

​
First Launch

1

Start niri

From a display manager: Log out and select “Niri” from your display manager (like GDM).From a TTY: Run niri-session (for systemd/dinit) or niri --session (for other init systems).Windowed mode: Run niri inside an existing desktop session for testing (note: this is mainly for development and may have hotkey issues).
2

Test basic functionality

Try these default hotkeys:
  • Super + T: Open terminal (Alacritty)
  • Super + D: Open application launcher (fuzzel)
  • Super + Shift + E: Exit niri
When running in windowed mode, the Mod key is Alt instead of Super.
3

Install essential software

niri requires additional software for full desktop functionality. See the Essential Software page for required components like notification daemons and portals.
4

Configure niri

Check the Configuration documentation to customize niri to your preferences. The config file is located at ~/.config/niri/config.kdl.

​
Platform-Specific Notes

NVIDIA drivers have a known issue with high VRAM usage. Apply the manual fix documented in the NVIDIA guide.If you experience a black screen:
  1. Update NVIDIA drivers to a version that supports GBM
  2. Enable kernel modesetting by adding nvidia-drm.modeset=1 to your kernel command line
Follow distribution-specific guides for Wayland compositor setup.
If you get a black screen on TTY startup, niri may have detected the wrong render device.First, list available devices:
ls -l /dev/dri/
Then add the render device to your config at ~/.config/niri/config.kdl:
debug {
    render-drm-device "/dev/dri/renderD128"
}
Try different renderD* or card* devices if the issue persists.
Ensure your system mesa version matches the niri mesa version to avoid black screen issues.On Intel graphics, you may need the workaround described in the NixOS wiki.Use the community-maintained flake:
nix build
./results/bin/niri
On non-NixOS systems, use NixGL:
nix run --impure github:guibou/nixGL -- ./results/bin/niri
Make sure to enable 3D acceleration in your VM settings for niri to work properly.

​
Desktop Environments

Several desktop environments officially support or work well with niri:

LXQt

Official niri support with complete desktop integration

XFCE

Many components work on Wayland, including with niri

Quickshell

Complete desktop shells like DankMaterialShell and Noctalia

COSMIC

Run COSMIC session with niri using cosmic-ext-extra-sessions

​
Next Steps

Essential Software

Set up notification daemons, portals, and authentication agents

Default Hotkeys

Learn the default keyboard shortcuts for window management

Configuration

Customize niri to match your workflow

Xwayland

Set up X11 application support

Build docs developers (and LLMs) love

Get started for freeTalk to us