Void Linux
stable rolling release
XBPS package manager, runit init

Initial Setup

Change root user shell to BASH

login: root

# chsh

/bin/bash

Add extra repositories

# xbps-install void-repo-nonfree

# xbps-install void-repo-multilib

# xbps-install void-repo-multilib-nonfree

Install essential tools

# xbps-install bash-completion vim screen wget mc htop nmap

Install cron and enable service

# xbps-install cronie

# ln -s /etc/sv/crond /var/service/

Set up periodic SSD TRIM

# vim /etc/cron.weekly/fstrim

#!/bin/sh

fstrim /

# chmod u+x /etc/cron.weekly/fstrim

Install microcode / firmware

# xbps-install intel-ucode

or

# xbps-install linux-firmware-amd

and then regenerate initramfs for the applicable kernel version

# xbps-reconfigure -f linux6.12

Add Desktop GUI

Install niri (Wayland)

# xbps-install niri

Example niri config.kdl ➔ https://github.com/wizetek/niri

For an integrated desktop solution install Noctalia shell ➔ https://docs.noctalia.dev/

Alternatively, roll your own by setting up individual desktop components:

Install desktop companion utilities

# xbps-install alacritty fuzzel swaylock swayidle swaybg mako xwayland-satellite

Install desktop toolbar and toolbar fonts

# xbps-install Waybar font-awesome6

Note: If Waybar fails to start, make sure PipeWire is running.

Install system fonts

# xbps-install dejavu-fonts-ttf terminus-font noto-fonts-ttf noto-fonts-cjk noto-fonts-emoji

Install elogind for session management along with D-Bus for inter-process communication and enable both services

# xbps-install elogind

# ln -s /etc/sv/elogind /var/service/

# ln -s /etc/sv/dbus /var/service/

Note: Package dbus gets installed automatically with elogind.

Install sound server and tools

# xbps-install pipewire alsa-pipewire pavucontrol

and if using elogind

# xbps-install wireplumber-elogind

Note: Packages wireplumber (session and policy manager) and pulseaudio-utils get installed automatically along with pipewire. PulseAudio interface is provided by PipeWire (symlink pipewire-pulse -> pipewire).

Install video acceleration (Intel and Nvidia)

# xbps-install mesa-vaapi mesa-vdpau

Install OpenGL support

# xbps-install mesa-dri

System Updates and Maintenance

Update all installed packages (--sync --update)

# xbps-install -Su

If required, update the package manager first

# xbps-install -u xbps

List and remove old kernel versions

# vkpurge list

# vkpurge rm 6.12.11_1

or remove all

# vkpurge rm all

List updated system configuration files (similar to Arch Linux's pacdiff)

# xdiff -l

and then visually merge diffs and remove duplicate files

# xdiff

Same as above performed manually

# updatedb

# locate '/etc/*.new-*'

...

# vimdiff /etc/rc.conf /etc/rc.conf.new-20250212_2

# rm /etc/rc.conf.new-20250212_2

Pro Tips

Avoid kernel updates and RAMdisk image rebuilds by placing on hold packages which cannot be otherwise removed (--mode)

# xbps-pkgdb -m hold linux6.18

# xbps-pkgdb -m hold linux-firmware-amd linux-firmware-nvidia linux-firmware-broadcom

Force the update later if needed (--force)

# xbps-install -Suf linux6.18

Useful command aliases

# Make aliases work with sudo

alias sudo='sudo '

# Make pkexec pop up a GUI auth dialog

alias pkexec="pkexec env DISPLAY=$DISPLAY XAUTHORITY=$XAUTHORITY WAYLAND_DISPLAY=$XDG_RUNTIME_DIR/$WAYLAND_DISPLAY XDG_RUNTIME_DIR=/run/user/0"

alias Mun='xbps-install -Mun' # --memory-sync --update --dry-run

alias Su='sudo xbps-install -Su' # --sync --update

alias QS='xbps-query -S' # --show

alias Qs='xbps-query -s' # --search

alias Rs='xbps-query -Rs' # (Repository) --search

alias Ql='xbps-query -l' # --list-pkgs

alias Qm='xbps-query -m' # --list-manual-pkgs

alias QH='xbps-query -H' # --list-hold-pkgs

alias QL='xbps-query -L' # --list-repos

alias Qf='xbps-query -f' # --files

alias Qx='xbps-query -x' # --deps

alias QX='xbps-query -X' # --revdeps

alias RR='sudo xbps-remove -R' # --recursive

alias Ro='sudo xbps-remove -o' # --remove-orphans

alias RO='sudo xbps-remove -O' # --clean-cache

Handy function to perform system updates inside a terminal multiplexer

Su() {

    [[ $EUID != 0 ]] && local sudo_cmd='sudo '

    if [[ $TERM == screen* ]]; then

        ${sudo_cmd}xbps-install -Su

        if [[ $? == 16 ]]; then

            ${sudo_cmd}xbps-install -u xbps

            ${sudo_cmd}xbps-install -u

        fi

    else

        screen -DRq maint sh -c "Su; exec $SHELL"

    fi

}

Package Management

X Binary Package System (XBPS)

List repositories (--list-repos)

# xbps-query -L

Search packages available in repositories as well as installed packages (--repository --search)

# xbps-query -Rs "window manager"

Search only installed packages

# xbps-query -s vim

Search using regular expressions

# xbps-query --regex -Rs '^neo.*qt'

Update all installed packages (--sync --update)

# xbps-install -Su

Only check for updates without writing to database (--memory-sync --update --dry-run)

# xbps-install -Mun

or in two steps: sync to disk, then initiate update without taking action

# xbps-install -S

# xbps-install -un

Install a package (-S --sync will first get updated data for remote repo index)

# xbps-install -S Waybar

or

# xbps-install Waybar

Note: Package names are case sensitive.

Reinstall a package (--force)

# xbps-install -f vim

or use the -f flag twice to also overwrite configuration files

# xbps-install -ff vim

Only download packages without installing (--download-only)

# xbps-install -D vim

Downgrade a package using local cache file (--repository --force)

# xbps-install -R /var/cache/xbps/ -f vim-9.1.1215_3

but first add to the local repository the old package version (package file must be in cache)

# xbps-rindex -a /var/cache/xbps/vim-9.1.1215_3.xbps

Hold / prevent a package from upgrade (--mode)

# xbps-pkgdb -m hold linux

Force upgrade anyway even while held

# xbps-install -u -f linux

Unhold later

# xbps-pkgdb -m unhold linux

Set package as automatically installed

# xbps-pkgdb -m auto vim

or (--automatic)

# xbps-install -A vim

Package will become an orphan if no other packages depend on it anymore.

Remove a package

# xbps-remove inxi

and also remove all dependencies (--recursive)

# xbps-remove -R inxi

Remove orphaned packages (--remove-orphans)

# xbps-remove -o

Remove old packages from cache (--clean-cache)

# xbps-remove -O

List all installed packages (--list-pkgs)

# xbps-query -l

List manually installed packages (--list-manual-pkgs)

# xbps-query -m

List packages on hold (--list-hold-pkgs)

# xbps-query -H

List package orphans (--list-orphans)

# xbps-query -O

Show information about installed package

# xbps-query -S vim

Mode -S (--show) is the default for query and can be skipped

# xbps-query vim

Show information about a package which is not installed

# xbps-query -R gvim

List files installed by a package (--files)

# xbps-query -f vim

Show which installed package owns the file (--ownedby)

# xbps-query --regex -o bin/vim

List package dependencies (--deps)

# xbps-query -x vim

List package reverse dependencies (--revdeps)

# xbps-query -X sed

or if not installed

# xbps-query -R -X awk

Show build options for binary packages

$ xbps-query -R --property=build-options vim

Reconfigure installed package (--force)

# xbps-reconfigure -f fontconfig

and dependencies (--deps)

# xbps-reconfigure -f -x fontconfig

or full dependency tree

# xbps-reconfigure -f -x --fulldeptree fontconfig

Global options

xbps-install, xbps-query
-n, --dry-run Do not do anything
-y, --yes Do not ask for confirmation

xbps-install, xbps-remove
-f, --force Force reinstall / removal

-v, --verbose Verbose

Advanced System Configuration

Change package repository mirrors

# xbps-install xmirror

# xmirror

# xbps-install -S

and optionally check

# xbps-query -L

# ls /etc/xbps.d/*repo*

Configure XBPS in xbps.d and set some useful options

# cp /usr/share/xbps.d/xbps.conf /etc/xbps.d/

# vim /etc/xbps.d/xbps.conf

ignorepkg=sudo

preserve=/etc/passwd

preserve=/etc/group

keepconf=true

virtualpkg=doas:opendoas

virtualpkg=waybar:Waybar

How to install doas and remove sudo

# xbps-install opendoas

# vim /etc/xbps.d/xbps.conf

ignorepkg=sudo

# xbps-remove sudo

Note: Package sudo depends on base-system and cannot be removed even with the -f, --force option. It must be added to the ignore list in xbps.conf in order to be removed.

List all alternatives

# xbps-alternatives -l

or only alternatives from a package (e.g. vi, vim)

# xbps-alternatives -l neovim

or match a group (e.g. nvi, vim-common, neovim)

# xbps-alternatives -l -g vi

Set alternatives for a package

# xbps-alternatives -s neovim

or for a group

# xbps-alternatives -g vi -s vim-common

How to change the default initramfs generator – replace dracut kernel hooks with mkinitcpio

# xbps-install mkinitcpio

# xbps-alternatives -l -g initramfs

# xbps-alternatives -s mkinitcpio

# xbps-reconfigure -f linux6.12

Reconfiguring kernel package forces regeneration of initramfs images.

Install zramen and enable service

# xbps-install zramen

# ln -s /etc/sv/zramen /var/service/

Set the amount of memory (defaults to 25%)

# vim /etc/sv/zramen/conf

export ZRAM_SIZE=50

and also suppress messages on tty1

export ZRAMEN_QUIET=1

Restart service

# sv restart zramen

Send hostname set in /etc/hostname to DHCP server

# vim /etc/dhcpcd.conf

hostname

Fix "Too many open files" error in Alacritty

# vim /etc/sysctl.conf

# Default was 128

fs.inotify.max_user_instances = 256

# sudo sysctl -p

Suppress kernel messages on tty1

# vim /etc/sysctl.conf

kernel.printk = 3 3 3 3

Build Packages From Source

Some packages are not built and distributed by Void Linux due to large size or legal restrictions. These packages still have their build templates and can be locally built and installed.

The Void source packages collection
void-packages ➔ https://github.com/void-linux/void-packages

Clone the void-packages git repository

$ git clone https://github.com/void-linux/void-packages.git

Install the recommended bootstrap packages into masterdir inside void-packages directory

$ cd void-packages

$ ./xbps-src binary-bootstrap

To build packages marked as restricted, modify etc/conf (overrides etc/defaults.conf) in the cloned repository

$ echo XBPS_ALLOW_RESTRICTED=yes >> etc/conf

Check which package templates contain restricted=yes

$ grep -rl '^restricted=' srcpkgs/

Show supported build options for a source package

$ ./xbps-src show-options zoom

Build a package – available afterward in hostdir/binpkgs or hostdir/binpkgs/nonfree

$ ./xbps-src pkg google-chrome

Install the built package (--repository)

# xbps-install -R hostdir/binpkgs/nonfree google-chrome

or using xtools

# xi -f google-chrome

Optionally, lock / prevent the built package from getting replaced by system update

# xbps-pkgdb -m repolock <pkgname>

and then unlock later if needed

# xbps-pkgdb -m repounlock <pkgname>

Note: For newly added and updated packages, check existing git pull requests: open (submitted and awaiting approval) and closed (merged or rejected).

Check for new upstream releases

$ ./xbps-src update-check <pkgname>

Update locally built packages

$ cd void-packages

$ git pull

$ sudo xbps-install -Su

$ ./xbps-src update-sys

update-sys updates all system packages
update-local recompiles only custom-built binaries

Keep the bootstrap packages updated to the latest available version in repositories

$ ./xbps-src bootstrap-update

If ever needed, remake the masterdir (if bootstrap-update is not enough)

$ ./xbps-src zap

$ ./xbps-src binary-bootstrap

Create a blank package template (akin to Arch Linux PKGBUILD)

$ xnew <pkgname>

In some cases an override file update is needed in addition to template

Edit

$ vim void-packages/srcpkgs/<pkgname>/template

Update checksum

$ xgensum -f -i <pkgname>

Lint

$ xlint <pkgname>

Build

$ ./xbps-src pkg <pkgname>

The XBPS source packages manual ➔ https://github.com/void-linux/void-packages/blob/master/Manual.md

xbps-src tutorials ➔ https://xbps-src-tutorials.github.io/

runit Init System

Start, stop, restart, reload, status of services

# sv up sshd

# sv down wpa_supplicant

# sv restart chronyd

# sv reload sshd

# sv status sshd

# sv status /var/service/*

List enabled services

# ls /var/service/

List available services

# ls /etc/sv/

Enable service

# ln -s /etc/sv/ntpd /var/service/

Note: /var/service is a symlink to /run/runit/runsvdir/current which is a symlink to /etc/runit/runsvdir/current where current is a symlink to either default or single.

Disable service

# rm /var/service/ntpd

or

# unlink /var/service/ntpd

Prevent service from starting at boot

# touch /etc/sv/sshd/down

Switch runlevel (runit-void package provides single and default)

# runsvchdir single

# runsvchdir default

Suspend to RAM (equivalent to systemd's systemctl suspend)

# zzz