This flake contains nix packages for niri, a scrollable-tiling Wayland compositor. You can try it right now: add the binary cache with cachix use niri and then nix run github:sodiboo/niri-flake. You can also try the latest commit to the main branch with nix run github:sodiboo/niri-flake#niri-unstable.

This flake also contains NixOS and home-manager modules to install all necessary components of a working Wayland environment, and to let you manage your configuration declaratively, validating it at build-time. This ensures that your config's schema is always in sync with the installed version of niri.

The main location for documentation is docs.md. The most important outputs are overlays.niri and nixosModules.niri. You may also use my configuration as a reference at github:sodiboo/nix-config

The rest of this README covers miscellaneous topics related to this flake or repo as a whole.

Feel free to contact me at @sodiboo:arcticfoxes.net in the #niri:matrix.org channel or through GitHub issues if you have any questions or concerns.

A note on the automated pull requests in this repository

This repository uses automated pull requests extensively in order to automatically update the lockfile. If you wish to view pull requests made by humans, you can filter for is:pr -label:automated.

This is done in order to keep the niri-unstable version up-to-date. Niri doesn't have an inherent "unstable" versioning scheme (like e.g. Rust or NixOS does) and that terminology is specific to this flake. It is just the latest commit to main. It's equivalent to niri-git on the AUR.

Previously, this was done by telling you to override the niri-src input with the latest version (which puts it in your lockfile), but doing it here has two main benefits:

I can run various hooks to automatically update documentation with, at the very least, the niri version, but also other generated items such as listing the available actions (parsed from source code and enumerated in docs.md).
I can perform checks on the updated lockfile to ensure that nothing breaks with new niri updates.

There are two less obvious benefits:

By requiring the build job to succeed, i can ensure that the latest niri versions are always in my binary cache before the pull request is merged. This means you won't need to build it locally.
By also automatically updating nixpkgs, i can run checks to ensure the modules keep working with the latest nixpkgs.

Currently, there is no home-manager input to this flake since i felt it was unnecessary for just checks, and therefore configurations involving home-manager are not automatically tested at this time.

Binary Cache

I have a binary cache for this flake's outputs. niri.cachix.org hosts builds of niri-stable and niri-unstable for nixos-unstable and nixos-24.05. It only contains builds for x86_64-linux for the time being, mainly because GitHub Actions doesn't support other platforms. (and i do not wish to use qemu for this)

Note

This binary cache is managed by me, sodiboo. By using it, you are trusting me to not serve you malicious software. Using a binary cache is entirely optional.

If you do not wish to use my binary cache, but still want the convenience of one, you could set programs.niri.package = pkgs.niri;, which is provided by nixpkgs. This package will receive updates slower.

If you use NixOS, add the niri.nixosModules.niri module and don't enable niri yet. Rebuild your system once to enable the binary cache, then enable niri. You can set niri-flake.cache.enable = false; to prevent this from happening.

If you're not using the NixOS module, you can add the cache to your system by running cachix use niri. This works on any system with nix installed, not just NixOS.

Using `niri-unstable`

Both niri.nixosModules.niri and niri.homeModules.niri provide the option to use a custom version of niri. This is done by setting programs.niri.package to the desired derivation. If you want to use the unstable version of niri, you can set it like so:

{pkgs, ...}: {
  nixpkgs.overlays = [ inputs.niri.overlays.niri ];
  programs.niri.package = pkgs.niri-unstable;
}

You can also set the package to the one from nixpkgs (pkgs.niri), which will likely receive updates slower than the niri-stable provided here.

niri.homeModules.config also provides the option to set the package. This won't install niri by itself, but it does set the package version used for build-time validation.

Configuration of niri

programs.niri.settings is the preferred way to configure niri. This is provided by niri.homeModules.config, which is automatically imported when using home-manager as a NixOS module. All options are documented in docs.md.

{
  programs.niri.settings = {
    outputs."eDP-1".scale = 2.0;
  };
}

If for whatever reason you want or need to override this, you can set programs.niri.config. You should give this option structured output from niri.lib.kdl.

{
  programs.niri.config = with inputs.niri.lib.kdl; [
    (node "output" "eDP-1" [
      (leaf "scale" 2.0)
    ])
  ];
}

But you can also pass it a string:

{
  programs.niri.config = ''
    output "eDP-1" {
      scale 2.0
    }
  '';
}

or set programs.niri.config = null; to prevent this module from generating a config file. By default, it will generate a config file based on programs.niri.settings if it is not null.

For debugging (primarily development of this flake i guess), there is also programs.niri.finalConfig which is always a string (or null) and represents the final config file that will be end up in your config directory.

Note

programs.niri.settings is not guaranteed to be compatible with niri versions other than the two provided by this flake.
In particular, this means that i do not guarantee compatibility with the one from nixpkgs at all times (i.e. when nixpkgs is lagging behind due to build failures or other reasons).
In practice, you will not have an issue with this unless you are running old versions of niri that are 2 or more releases behind. I will try my best not to break compatibility with nixpkgs.

This does not apply to programs.niri.config as it is inherently version-agnostic and still provides build-time validation.

Stylix

A module is provided to integrate with Stylix. To use this, the main prerequisite is that you don't ever set programs.niri.config; this will override everything from programs.niri.settings, which is where the stylix module places config.

If you've installed home-manager and stylix as a NixOS module, then this will be automatically imported. Else, you'll have to import niri.homeModules.stylix yourself.

The stylix module provides the option to disable it: stylix.targets.niri.enable = false;. Note that it is already disabled by default if you have stylix.autoEnable set to false.

When enabled, the stylix module will set the active/inactive border colors, and set layout.border to be on by default. It also sets the xcursor theme and size.

Additional notes

When installing niri using the modules provided by this flake:

The niri package will be installed, including its systemd units and the niri-session binary.
xdg-desktop-portal-gnome will be installed, as it is necessary for screencasting.
The GNOME keyring will be enabled. You probably want a keyring installed.

Specifically the NixOS module provides the following additional functionality:

It will enable polkit, and run the KDE polkit agent.
If you prefer a different polkit authentication agent, you can set systemd.user.services.niri-flake-polkit.enable = false;
It enables various other features that Wayland compositors may need, such as dconf, opengl and default fonts. It also adds a pam entry for swaylock, which is necessary if you wish to use swaylock.

Some additional software you may want to install to get a full desktop experience:

A notification daemon such as mako
A bar such as waybar
A launcher such as fuzzel

These will usually be installed through home-manager. No particular configuration is necessary for them to work with niri specifically, as they generally start on graphical-session.target which includes niri.

If using waybar, you'll want to set programs.waybar.settings.mainBar.layer = "top";, to ensure it is visible over applications running in niri. You'll also wanna set programs.waybar.systemd.enable = true; which i've found seems to exceed the default restart limit of 5, so you may want to run systemctl --user reset-failed waybar.service in spawn-at-startup to get it to start.

For electron applications such as vscode, you will want to set programs.niri.environment."NIXOS_OZONE_WL" = 1. Several packages in nixpkgs look for this variable, and pass some ozone flags in that case. Note that you must use niri-session to start niri for this to have any effect, because running just niri will not set the neccecary environment variables.

Visual Studio Code does not properly detect the correct keyring to use on my system. It works fine if you launch it with code --password-store="gnome-libsecret". You persist this flag in Preferences > Configure Runtime Arguments (argv.json), by setting "password-store": "gnome-libsecret".