Installation

Nokkvi is Linux only and built/tested on Arch Linux (Wayland/Hyprland) with PipeWire. Three install paths:

Arch Linux (AUR) — recommended

Two AUR packages are published. Install whichever fits — they conflict, so you can only have one at a time.

Package	Install	What it does
nokkvi-bin	yay -S nokkvi-bin	Downloads the prebuilt x86_64 binary from the latest GitHub release. Fastest install, recommended for most users.
nokkvi-git	yay -S nokkvi-git	Builds from the latest main HEAD. Picks up unreleased fixes between tagged releases. Slower install (cargo build), needs a Rust toolchain.

(Replace yay with paru or any other AUR helper if you prefer.)

Runtime dependencies are pulled in automatically by pacman.

Keeping nokkvi-git current: a regular yay -Syu won’t rebuild it between AUR pkgver bumps. Run yay -Syu --devel to have yay check main for new commits and rebuild if there are any.

To uninstall: yay -Rns nokkvi-bin (or nokkvi-git). Per-user files are left in place — remove them manually with rm -rf ~/.config/nokkvi/ ~/.local/state/nokkvi/ ~/.cache/nokkvi/ if you want a full wipe. Config (config.toml, themes/, sfx/) lives in ~/.config/nokkvi/; runtime state (app.redb, nokkvi.log) lives in ~/.local/state/nokkvi/; MPRIS album-art (mpris-art-<pid>-<cover_id>.jpg) lives in ~/.cache/nokkvi/.

Other Linux distros — prebuilt binary

Grab the latest tarball from GitHub Releases. Each release ships:

• nokkvi-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
• nokkvi-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz.sha256

Verify, extract, install:

curl -LO https://github.com/f-o-o-g-s/nokkvi/releases/download/vX.Y.Z/nokkvi-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/f-o-o-g-s/nokkvi/releases/download/vX.Y.Z/nokkvi-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz.sha256
sha256sum -c nokkvi-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz.sha256
tar xzf nokkvi-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz
cd nokkvi-vX.Y.Z-x86_64-unknown-linux-gnu
./install.sh

install.sh places per-user files (no sudo):

• ~/.local/bin/nokkvi — binary
• ~/.local/share/applications/org.nokkvi.nokkvi.desktop — launcher entry
• ~/.local/share/icons/hicolor/scalable/apps/org.nokkvi.nokkvi.svg — SVG icon
• ~/.local/share/icons/hicolor/512x512/apps/org.nokkvi.nokkvi.png — PNG raster icon fallback

You’ll need pipewire, alsa-lib, and fontconfig installed system-wide at runtime:

# Debian / Ubuntu (use libasound2 on releases older than Ubuntu 24.04)
sudo apt install pipewire libasound2t64 fontconfig

# Fedora
sudo dnf install pipewire alsa-lib fontconfig

The binary is built on GitHub’s current Ubuntu runner, so it needs a reasonably recent glibc (currently Ubuntu 24.04 / glibc ≥ 2.39). Modern rolling distros (Arch, Fedora, recent Ubuntu/Debian) work; very old enterprise distros may not.

Launching

Launch Nokkvi from your application launcher, or run nokkvi from a terminal.

Build from source

For contributors, AUR maintainers, or users on architectures we don’t ship binaries for.

# System dependencies (Arch)
sudo pacman -S pipewire alsa-lib fontconfig pkgconf cmake

# Clone and build
git clone https://github.com/f-o-o-g-s/nokkvi.git
cd nokkvi
cargo build --release
./install.sh

The CI build pipeline produces what nokkvi-bin ships, so building locally from a tagged commit yields a functionally identical binary.

./install.sh auto-detects whether it’s running from an extracted release tarball or a source-tree build, and installs the binary from the right location either way.

For development workflow details — including the nightly rustfmt requirement and the test/clippy/format gates — see CONTRIBUTING.md in the repo.

Command-line flags

See Command Line for the full verb surface.