快速入门

快速开始

使用以下命令安装 niri 并搭配 Dux Modular Shell 以获得接近开箱即用的体验。

Fedora:

sudo dnf copr enable duxlabs/dms
sudo dnf install niri dms
systemctl --user add-wants niri.service dms

Arch Linux:

sudo pacman -Syu niri xwayland-satellite xdg-desktop-portal-gnome xdg-desktop-portal-gtk alacritty dux-shell matugen cava qt6-multimedia-ffmpeg
systemctl --user add-wants niri.service dms

Ubuntu 25.10 及以上:

sudo add-apt-repository ppa:duxlabs/dux-repo
sudo add-apt-repository ppa:duxlabs/dms
sudo apt update
sudo apt install niri dms

执行完这些命令后，注销并在显示管理器中选择 Niri，然后重新登录。 如果不使用显示管理器，可在 TTY 中运行 niri-session。

默认的 niri 配置会启动 Waybar，因此屏幕上可能会出现两个状态栏。
解决办法：先执行 pkill waybar 停止 Waybar，然后打开 ~/.config/niri/config.kdl，删除其中的 spawn-at-startup "waybar" 一行即可。

查看 Dux Modular Shell 的 合成器设置页面，了解如何配置特定于 DMS 的绑定和其他 niri 集成。

更慢但更稳妥的开始

获取 niri 最简单的方法是使用包管理器安装。 以下是一些选项：Fedora COPR 和 nightly COPR（由我个人维护），NixOS Flake（sodiboo/niri-flake 的维护分支），以及下面 repology 中提供的一些更多选项, 包括适用于基于 Debian 发行版的pacstall 软件包。 如果您想自己编译 niri，请参阅 构建 部分；如果您想打包 niri，请参阅 打包 niri 页面。

安装后，从您的显示管理器（如 GDM）启动 niri。 按 SuperT 运行终端 (Alacritty)，按 SuperD 运行应用程序启动器 (fuzzel)。 要退出 niri，请按 SuperShiftE。

如果您不使用显示管理器，应该在 TTY 运行 niri-session（systemd/dinit）或 niri --session（其他）。 --session 标志会让 niri 将其环境变量全局导入到系统管理器和 D-Bus，并启动其 D-Bus 服务。 niri-session 脚本将额外将 niri 作为 systemd/dinit 服务启动，该服务会启动某些服务（如 Portals）所需的图形会话目标。

Warning

直接在 TTY 中运行 niri 意味着一旦退出或崩溃，用户将直接退回到无保护、未锁屏的 shell 提示符界面。 建议配合显示管理器使用以规避此安全隐患。

您也可以在现有的桌面会话中运行 niri。 然后它将作为一个窗口打开，您可以在其中试用它。 请注意，此窗口模式主要用于开发，因此存在一些错误（特别是快捷键方面的问题）。

接下来，请参阅 重要软件列表，了解正常桌面使用所需的软件，如通知守护进程和 Portals。 同时，查看 配置介绍 页面开始配置 niri。 在那里您可以找到包含所有选项的详细文档和示例的其他页面的链接。 最后，Xwayland 页面解释了如何在 niri 上运行 X11 应用程序。

桌面环境

一些桌面环境和 shell 可以与 niri 协同工作，并提供更开箱即用的体验：

• LXQt 官方支持 niri，有关设置详情，请参阅 他们的 wiki。
• 许多 XFCE 组件可以在 Wayland 上运行，包括 niri。有关详情，请参阅 他们的 wiki。
• 有一些完整的桌面 shell 支持 niri，例如 Dux Modular Shell 和 Noctalia。
• 您可以使用 cosmic-ext-extra-sessions 在 niri 上运行 COSMIC 会话。

默认应用程序

如果您将 niri 与 GNOME 或 KDE 一并安装，并希望保留它们的默认应用关联（例如使用哪个图片查看器或视频播放器），可以像这样为它们的 mimeapps.list 创建符号链接：

ln -s /usr/share/applications/gnome-mimeapps.list ~/.local/share/applications/niri-mimeapps.list

NVIDIA

NVIDIA 驱动程序目前由于堆重用特性存在高显存占用问题。 如果您在 NVIDIA GPU 上运行 niri，建议应用 此处 记录的手动修复。

NVIDIA GPU 在运行 niri 时可能会出现问题（例如，从 TTY 启动时屏幕保持黑屏）。 有时，这些问题可以修复。 您可以尝试以下方法：

1. 更新 NVIDIA 驱动程序。您需要足够新的 GPU 和驱动程序以支持 GBM。
2. 确保内核模式设置已启用。这通常涉及将 nvidia-drm.modeset=1 添加到内核命令行中。查找并遵循您的发行版的指南。来自其他 Wayland 合成器的指南可能会有所帮助。

Asahi、ARM 和其他 kmsro 设备

在部分此类系统上，niri 无法正确检测主渲染设备。 如果您在 TTY 上启动 niri 时遇到黑屏，可以尝试手动指定设备。

首先，找出您拥有的设备：

$ ls -l /dev/dri/
drwxr-xr-x@       - root 14 мая 07:07 by-path
crw-rw----@   226,0 root 14 мая 07:07 card0
crw-rw----@   226,1 root 14 мая 07:07 card1
crw-rw-rw-@ 226,128 root 14 мая 07:07 renderD128
crw-rw-rw-@ 226,129 root 14 мая 07:07 renderD129

您可能有一个 render 设备和两个 card 设备。

打开位于 ~/.config/niri/config.kdl 的 niri 配置文件，并像这样将您的 render 设备路径填入：

debug {
    render-drm-device "/dev/dri/renderD128"
}

保存，然后尝试再次启动 niri。 如果仍然出现黑屏，请尝试使用每个 card 设备。

Nix/NixOS

Mesa 驱动与 niri 版本不同步是一个常见问题，因此请确保您的系统 mesa 版本与 niri 的 mesa 版本匹配。 一旦遇到这种情况，您大概率会在从 TTY 尝试启动 niri 时遇到黑屏。

此外，在 Intel 显卡上，您可能需要 此处 描述的变通方法。

虚拟机

要在虚拟机中运行 niri，请确保启用了 3D 加速。

主要默认快捷键

在 TTY 上运行时，Mod 键是 Super。 在窗口中运行时，Mod 键是 Alt。

整体规则如下：如果某个快捷键用于切换目标，那么再添加 Ctrl 即可将焦点窗口或整列移动到那里。

快捷键	描述
ModShift/	显示重要的 niri 快捷键列表
ModT	启动 alacritty（终端）
ModD	启动 fuzzel（应用程序启动器）
SuperAltL	启动 swaylock（锁定屏幕）
ModQ	关闭焦点窗口
ModH 或 Mod←	聚焦左侧的一列
ModL 或 Mod→	聚焦右侧的一列
ModJ 或 Mod↓	聚焦列下方的窗口
ModK 或 Mod↑	聚焦列上方的窗口
ModCtrlH 或 ModCtrl←	将焦点列向左移动
ModCtrlL 或 ModCtrl→	将焦点列向右移动
ModCtrlJ 或 ModCtrl↓	将焦点窗口在列中向下移动
ModCtrlK 或 ModCtrl↑	将焦点窗口在列中向上移动
ModShiftHJKL 或 ModShift←↓↑→	聚焦侧面的显示器
ModCtrlShiftHJKL 或 ModCtrlShift←↓↑→	将焦点列移动到侧面的显示器
ModU 或 ModPageDown	切换到下方的工作区
ModI 或 ModPageUp	切换到上方的工作区
ModCtrlU 或 ModCtrlPageDown	将焦点列移动到下方的工作区
ModCtrlI 或 ModCtrlPageUp	将焦点列移动到上方的工作区
ModShiftU 或 ModShiftPageDown	将焦点工作区向下移动
ModShiftI 或 ModShiftPageUp	将焦点工作区向上移动
Mod[	将焦点窗口向左合并或弹出
Mod]	将焦点窗口向右合并或弹出
ModR 和 ModShiftR	在预设列宽之间向前和向后切换
ModM	最大化窗口
ModC	在视图中居中列
Mod-	将列宽减少 10%
Mod=	将列宽增加 10%
ModShift-	将窗口高度减少 10%
ModShift=	将窗口高度增加 10%
ModCtrlR	将窗口高度重置为自动
ModShiftF	切换焦点窗口的全屏状态
ModV	将焦点窗口在浮动和平铺布局之间移动
ModShiftV	在浮动和平铺布局之间切换焦点
PrtSc	截取区域截图。使用鼠标选择要截图的区域，然后按 空格 保存截图，或按 Escape 取消
AltPrtSc	将焦点窗口截图到剪贴板和 ~/Pictures/Screenshots/
CtrlPrtSc	将焦点显示器截图到剪贴板和 ~/Pictures/Screenshots/
ModShiftE 或 CtrlAltDelete	退出 niri

构建

首先，安装您的发行版的依赖项。

• Ubuntu 24.04:

  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
  

• Fedora:

  sudo dnf install gcc libudev-devel libgbm-devel libxkbcommon-devel wayland-devel libinput-devel dbus-devel systemd-devel libseat-devel pipewire-devel pango-devel cairo-gobject-devel clang libdisplay-info-devel
  

接下来，获取最新的稳定版 Rust：https://rustup.rs/

然后，使用 cargo build --release 构建 niri。

查看 Cargo.toml 了解构建功能列表。 例如，您可以使用 cargo build --release --no-default-features --features dinit,dbus,xdp-gnome-screencast 将 systemd 集成替换为 dinit 集成。

Warning

不要使用 --all-features 构建！

某些功能仅供开发调试使用。 例如，其中一项功能会将性能分析数据不断写入内存缓冲区中，直到耗尽所有内存。

NixOS/Nix

我们有一个社区维护的 flake，它提供了包含所需依赖项的 devshell。使用 nix build 构建 niri，然后运行 ./results/bin/niri。

如果您不在 NixOS 上，可能需要 NixGL 来运行生成的二进制文件：

nix run --impure github:guibou/nixGL -- ./results/bin/niri

手动安装

如果直接安装而不使用包管理，推荐的目标文件位置会略有不同。 在这种情况下，请将文件放入下表所示的目录中。 具体位置可能因发行版而异。

不要忘记确保 niri.service 中 niri 的路径是正确的。 默认为 /usr/bin/niri。

文件	目标位置
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 (systemd)	/etc/systemd/user/
resources/niri-shutdown.target (systemd)	/etc/systemd/user/
resources/dinit/niri (dinit)	/etc/dinit.d/user/
resources/dinit/niri.target (dinit)	/etc/dinit.d/user/