Installation

Installation

This guide covers installation, trial runs, and manual builds.

Requirements

• Wayland session.
• GTK 4.18 or newer plus gtk4-layer-shell (pkg-config: gtk4-layer-shell-0).
• D-Bus session bus.
• A supported user service manager for installer-managed startup.
  • default: systemd --user
  • supported alternatives: dinit --user, user runit, and user s6-rc
• Rust toolchain for builds and the installer.
• The unixnotis-svg-renderer helper is included in release archives and is installed beside the daemon, center, popup, and CLI binaries.

Optional widget backends:

• wpctl or pactl for volume.
• nmcli for Wi-Fi toggles.
• brightnessctl for brightness.
• bluetoothctl + dbus-monitor for Bluetooth.
• rfkill + udevadm for airplane mode.
• Optional Night backend: hyprsunset, gammastep, wlsunset, or sunsetr. UnixNotis creates editable helper scripts under the config directory when the shipped default Night toggle points at them.

Check the GTK version before starting an installation:

pkg-config --modversion gtk4

The installer refuses GTK 4.17 and older before writing binaries, service files, or configuration. The same baseline is used by gtk4 and gdk4-wayland; removing the version check does not make an older runtime compatible.

Installer (recommended)

Downloaded release archives include unixnotis-installer at the archive root and the runtime binaries under bin/. Extract the archive, keep the files together, and run:

./unixnotis-installer

The archive also includes unixnotis-release.json. The installer checks that manifest and the listed bundled binaries, including unixnotis-svg-renderer, before copying anything into $HOME/.local/bin.

When installing from a source checkout, the installer builds and installs binaries, writes config and theme files, and manages the selected user service:

cargo run --release -p unixnotis-installer

Installer actions:

• builds release binaries from source, or verifies bundled release binaries from an archive
• installs to $HOME/.local/bin
• writes config.toml, contained active CSS layers, and default helper scripts under $XDG_CONFIG_HOME/unixnotis; an external configured stylesheet is never created or replaced
• follows existing [theme] paths during repair, preserves existing regular files, and never follows an unsafe external path or symlink
• adds a managed PATH block to the active shell startup file and .profile when needed
• writes and enables the selected user-service artifacts
• syncs the live Wayland session environment before starting the daemon
• installs and verifies the bounded unixnotis-svg-renderer helper used for local SVG artwork
• adds a managed Hyprland startup block when an active Hyprland config is found

The installer shows the current UnixNotis version in the welcome screen and performs a best-effort GitHub release check. A failed update check does not block installation.

Source installs select Cargo binary targets rather than assuming every executable has a matching package name. The progress screen keeps the newest build output visible, so a failed compile shows the final Cargo diagnostic instead of only the first setup lines. Subprocess readers retain at most 32 KiB from one physical line and drain the remainder without growing that buffer. Each retained line is then sanitized for terminal and bidirectional controls and capped at 8,192 characters before the TUI wraps or stores it.

Release manifests, workspace installer metadata, Cargo target discovery, install, and uninstall all share one fixed managed-binary policy. An entry must be one supported filename, never an absolute path or a name containing path components. Source-root discovery parses [workspace].members and requires the real daemon and core crate paths; crate names in comments do not identify a checkout. When Cargo target metadata is available, an explicit installer list must match real workspace binary targets, and an empty target inventory never broadens what may be copied or removed.

Reset and restore

The installer’s Reset config option opens a submenu:

• Reset to defaults: backs up and atomically replaces the fixed stock targets: config.toml, base.css, panel.css, popup.css, widgets.css, media.css, and the four scripts/unixnotis-blue-light-* helpers. CSS files at custom [theme] paths are not reset.
• Restore backup: restores files present in the selected snapshot to validated contained paths. Script targets are validated and written with mode 0755; missing or unsafe entries are skipped with warnings.

Backups are created during reset and stored under: $XDG_CONFIG_HOME/unixnotis/Backup-YYYY-MM-DD-HHMMSS[-NNN]

The optional -NNN suffix is added only when another reset backup is created in the same second.

The same reset operation is available without the installer UI:

noticenterctl preset reset-config
noticenterctl preset reset-config --yes

--yes is required for non-interactive use. Reset does not delete theme.toml, exported theme directories, custom assets, or unrelated files outside the fixed stock targets. It reports the backup path. The installer restore flow restores the files present in that snapshot and reapplies helper-script executable permissions.

Retention is controlled by $XDG_CONFIG_HOME/unixnotis/installer.toml:

[backups]
keep = 3

After a successful install, the UI offers optional build acceleration. It can write a local .cargo/config.toml that uses a wrapper script for sccache and mold when available. This is opt-in, local to the repository, and safe to remove if not desired.

Build acceleration details:

• no files are written when neither sccache nor mold is available
• unmanaged existing .cargo/config.toml files are left alone
• installer-owned configs are recognized by the Generated by unixnotis-installer marker
• the wrapper prefers sccache, adds mold when available, and falls back to plain rustc
• Clippy is forwarded directly to avoid wrapper argument conflicts

Service manager selection

For the manager-specific environment files, status commands, and recovery steps, see Service Managers and Session Environment.

systemd --user is the default and remains the most tested path. Non-systemd setups can select another backend:

cargo run --release -p unixnotis-installer -- --service-manager dinit
cargo run --release -p unixnotis-installer -- --service-manager runit
cargo run --release -p unixnotis-installer -- --service-manager s6

The same setting can be exported for repeated installer runs:

UNIXNOTIS_SERVICE_MANAGER=runit cargo run --release -p unixnotis-installer

Accepted values:

• systemd or systemd-user
• dinit or dinit-user
• runit or runit-user
• s6 or s6-user

CLI selection takes priority over UNIXNOTIS_SERVICE_MANAGER.

Backend notes:

• systemd writes unixnotis-daemon.service under the user unit directory and runs systemctl --user daemon-reload when the unit changes.
• dinit writes a user service plus a boot.d enablement link. If the user boot service does not include boot.d, the installer can start UnixNotis now but warns that next-login autostart may need dinit user setup.
• runit writes a managed service directory with a generated run script. The chpst command must be available. UNIXNOTIS_RUNIT_SERVICE_DIR overrides the service root, then SVDIR, then $HOME/.config/service.
• s6 writes local s6-rc service source, compiles a local database, and updates the live user database. UNIXNOTIS_S6_DATA_DIR overrides the source/database root, and UNIXNOTIS_S6RC_LIVE_DIR overrides the live root.

For dinit, runit, and s6, verify the service state after installation. These backends are newer than the systemd path and depend more heavily on the user service setup already running correctly.

Use one command to verify the selected artifact, status, D-Bus owners, and config:

noticenterctl doctor --verbose --service-manager dinit
noticenterctl doctor --verbose --service-manager runit
noticenterctl doctor --verbose --service-manager s6

Systemd verbose diagnostics include a small bounded journal window. The generated dinit, runit, and s6-rc artifacts do not install logger services or persistent log buffers, so doctor reports status and an informational log-unavailable note for those backends.

Session environment

The installer imports only the session values UnixNotis needs:

• WAYLAND_DISPLAY
• XDG_RUNTIME_DIR
• XDG_CURRENT_DESKTOP
• XDG_SESSION_TYPE
• XDG_SESSION_DESKTOP
• DISPLAY
• PATH

WAYLAND_DISPLAY and XDG_RUNTIME_DIR are required for installation from a live session. For systemd and dinit, the values are imported through the manager. For runit and s6, they are written into backend-owned env files before the service starts.

After a compositor restart or a manager migration, synchronize explicitly:

noticenterctl sync-session-environment

The command must run from the active compositor session. It does not create a fake display or copy credentials from an unrelated shell.

Shell PATH

Installed binaries are placed in $HOME/.local/bin. The installer adds a managed block:

# unixnotis-installer path entry
export PATH="$HOME/.local/bin:$PATH"

It updates the active shell startup file first (.zshrc for zsh, .bashrc for bash) and then .profile as a fallback. Existing PATH entries are detected, so repeated installs do not duplicate the block. The current terminal is not changed; open a new shell or export the PATH manually for the current session.

Hyprland startup

When Hyprland is detected, the installer updates the loaded Hyprland config with a managed UnixNotis bootstrap block. That block keeps the daemon environment fresh on new logins.

Current Hyprland Lua configs are preferred:

• $XDG_CONFIG_HOME/hypr/hyprland.lua
• fallback: $HOME/.config/hypr/hyprland.lua

Legacy hyprlang configs are still supported:

• $XDG_CONFIG_HOME/hypr/hyprland.conf
• fallback: $HOME/.config/hypr/hyprland.conf

If both files exist, UnixNotis targets the Lua config because newer Hyprland loads it first. Uninstall removes only the managed UnixNotis block and leaves user-managed startup lines alone.

Trial run

Trial mode temporarily replaces the current notification daemon and restores it on exit. Select “Trial run” in the installer UI.

Trial mode checks the current owner of org.freedesktop.Notifications, prints known notification daemon status, asks for confirmation, stops the active owner, and waits for the bus name to be released before UnixNotis starts.

Known daemons:

• mako
• dunst
• swaync
• notify-osd
• quickshell

Restore modes:

• auto: restart the matching systemd --user unit when active, otherwise restart the captured process command
• systemd: require an active known user unit and restore through systemctl --user start
• process: restore by spawning the captured argv from the previous process
• none: stop the previous daemon for the trial and do not restore it

Manual trial examples:

unixnotis-daemon --trial
unixnotis-daemon --trial --restore process
unixnotis-daemon --trial --restore none --yes

Trial mode only stops known daemons. If another process owns the notification bus, UnixNotis stops and reports that owner instead of guessing.

Build from source

cargo build --release

Run the daemon and UIs manually (Wayland session required):

cargo run --release -p unixnotis-daemon
cargo run --release -p unixnotis-center
cargo run --release -p unixnotis-popups

Open or close the panel:

cargo run --release -p noticenterctl -- open-panel
cargo run --release -p noticenterctl -- close-panel

User service

The installer manages the selected user service. The service runs the daemon from $HOME/.local/bin.

Common status commands:

systemctl --user status unixnotis-daemon.service
dinitctl --user status unixnotis-daemon
sv status "$HOME/.config/service/unixnotis-daemon"
s6-rc -l "${UNIXNOTIS_S6RC_LIVE_DIR:-/run/$USER/s6-rc}" -a list | grep unixnotis-daemon

Use the command that matches the selected backend and local service layout.

Uninstall

Run the installer and select uninstall to stop UnixNotis and remove:

• unixnotis-daemon, unixnotis-popups, unixnotis-center, unixnotis-css-validate, and noticenterctl from the selected user binary directory
• service-manager artifacts created for systemd, dinit, runit, or s6
• installer-managed Hyprland bootstrap and shell PATH blocks
• the persisted UnixNotis DND state file and its directory when that directory becomes empty

The config directory, themes, scripts, assets, and backups are retained as user data. Reset is the separate operation for replacing config files.

Hyprland configs may be regular files or dotfile symlinks whose resolved regular-file target stays inside $HOME. Install and uninstall preserve the symlink and update its target atomically. Links outside the home directory, dangling links, directory targets, and special-file targets are refused.

Uninstall removes only service artifacts that still match the installer-owned shape. If a service path was replaced with a symlink, special file, or unmarked directory, UnixNotis refuses to remove it automatically and prints the path for manual review.

First-run checklist

• Confirm the session type is Wayland (XDG_SESSION_TYPE=wayland).
• Confirm GTK 4.18+ and gtk4-layer-shell are installed.
• Confirm the compositor allows layer-shell surfaces.
• Run noticenterctl open-panel to validate panel control.