Installation

Nokkvi is Linux only and built/tested on Arch Linux (Wayland/Hyprland) with PipeWire. Four 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.

Nix

The repo ships a flake.nix, so there’s nothing to package first:

# Run it straight from GitHub, installing nothing
nix run github:f-o-o-g-s/nokkvi

# Build from a clone — the binary lands in ./result/bin/nokkvi
nix build

# Dev shell: cargo, rustc, clippy, rustfmt, rust-analyzer
nix develop

Supported systems are x86_64-linux and aarch64-linux. The package reads its version from Cargo.toml and its dependencies from Cargo.lock, so releases and dependency bumps need no flake edit.

The built binary is wrapped with an LD_LIBRARY_PATH covering the runtime libraries (PipeWire, ALSA, fontconfig, Wayland and X11, Mesa, Vulkan, D-Bus), and the .desktop file and icons are installed alongside it, so Nokkvi shows up in your launcher like any other install. An overlays.default is exported too, if you’d rather pull nokkvi into your own system flake.

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 clang

# 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.