Installation

On Arch Linux and derivatives, the installer installs build dependencies, clones main into ~/.local/share/kanade/src, and builds against your system libraries with cargo install --locked --root "$HOME/.cargo" --path .. Run it again to update. From a checkout, scripts/install builds that tree instead.

curl -fsSL https://raw.githubusercontent.com/0x1d1e/kanade/main/scripts/install | sh

Packages use paru if available, otherwise an existing yay, with --needed --noconfirm. If neither exists, the script tries sudo pacman -S --needed paru and stops if that fails. It does not build an AUR helper itself.

A standard desktop install adds niri and its portal, a Vulkan driver, audio, fonts, kitty, qt6ct and awww. It installs the user unit, icon and completions, and copies the default compositor configs only when missing. For niri, start the session with niri-session from a TTY. For Umbriel, use the startup path below.

Installer options

Options go after sh -s --:

curl -fsSL https://raw.githubusercontent.com/0x1d1e/kanade/main/scripts/install | sh -s -- --shell-only

Option	Effect
--shell-only	Omits desktop packages. A missing niri config is installed only with --niri or --sddm; those selections also include awww
--niri	Explicitly selects niri; leaves the default desktop package set enabled. Use --shell-only --niri to omit that set and install niri, awww and a missing niri config (unless --no-niri skips it)
--no-niri	Skips automatic niri package selection and its config; explicit --niri or --sddm still installs niri, and --sddm also overrides the config skip
--sddm	Installs SDDM, Qt dependencies and niri, sets up the theme overlay, and enables SDDM for the next boot without starting it
--sddm-greeter keep|niri	Chooses that login screen with --sddm; default is niri on hybrid NVIDIA, keep otherwise
--optional	Adds optional packages and enables bluetooth, upower and power-profiles-daemon; NetworkManager is left for you to enable
--ref REF	Builds that branch or tag instead of main; refused from a checkout
--yes	Accepted for compatibility
--uninstall	Removes the binary, completions, unit, icon, build checkout and owned SDDM files; keeps configs, packages and unit backups

SDDM setup can disable another enabled display manager when SDDM is not already enabled. See the canonical installation guide for the exact files and service steps.

Umbriel

Install Umbriel separately. Use --shell-only for an existing desktop, or --no-niri to keep desktop packages while skipping niri. Even shell-only copies dist/umbriel/config.toml when yours is missing, under $XDG_CONFIG_HOME/umbriel/config.toml (default ~/.config/umbriel/config.toml). Existing configs stay intact.

Keep Kanade started by Umbriel: the supplied config has [general] autostart = ["kanade"]. Add kanade once to an existing autostart list and put ~/.cargo/bin on Umbriel’s PATH. Bare kanade starts one recovery parent, which restarts its rendering child after an exit and retains acknowledged lock intent in memory. The unit stays tied to niri.service; no different unit is needed under Umbriel. Use one startup method per session.

The parent itself is not restarted, a hung child is not detected, and an ambiguous unlock can conservatively relock. Live renderer-crash recovery and replacement-lock authentication were observed with the lock Module enabled and with a persisted disable, including suppression of replacement lock/unlock hooks in the disabled run. No-desktop-flash remains unobserved; live logout/compositor shutdown and niri acceptance remain NOT RUN. Read Running Kanade for the tested candidate and evidence limits.

Kanade’s Auth Surface supports Umbriel through the selected compositor’s focused output. Live Umbriel registration, focused placement, Cancel/Escape and overview deferral passed on the candidate recorded in the Auth guide. A separate authorization check succeeded without an observed prompt or password entry; password/PAM authentication remains unverified. If you previously disabled the polkit Module, enable it with kanade module enable polkit and restart through Umbriel. To keep an external agent instead, leave the Module off. The installer does not install an external agent.

Manual build

From a source checkout:

cargo install --locked --root "$HOME/.cargo" --path .

Required: Rust, a C compiler, pkg-config, wayland, libxkbcommon, fontconfig, freetype, expat, vulkan-loader, libpulseaudio and linux-pam headers, plus a Vulkan driver matching your GPU. Run niri or Umbriel; Kanade prefers reachable Umbriel IPC, then niri.

For niri, install and enable the unit as described in Running Kanade. For Umbriel, retain compositor autostart as above.

Caution

Kanade must be the session’s only notification daemon: stop mako, dunst or other notification daemons and remove their startup entries, then restart Kanade. Using Kanade’s polkit agent under either compositor also requires stopping a competing agent and removing its startup entry. Registration retries automatically, up to 30 s between attempts, and logs kanade: polkit agent registered for this session after success.

See also

Running and updating, niri rules, SDDM, and known gaps.