Void Linux
 BSD-like stable rolling release
XBPS package manager, xbps-src builder, runit init

Initial Setup

Change root user shell to BASH

login: root

# chsh

/bin/bash

Add extra repositories (to be able to install for example package nmap)

# xbps-install void-repo-nonfree void-repo-multilib void-repo-multilib-nonfree

Install some essential tools

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

Install chrony (NTP – date & time sync) and enable the service

# xbps-install chrony

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

Install cron (scheduler) and enable the service

# xbps-install cronie

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

Install TLP (laptop battery life optimization) and enable the service

# xbps-install tlp

# ln -s /etc/sv/tlp /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) ➔ https://github.com/YaLTeR/niri

# xbps-install niri

Install X11 support and a terminal emulator

# xbps-install xwayland-satellite alacritty

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

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

• Alternatively, roll your own by adding individual desktop components:

  • Add desktop companion utilities

# xbps-install fuzzel swaylock swayidle swaybg mako

• Add 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 (-S, --sync) (-u, --update)

# xbps-install -Su

If required, update the package manager itself first

# xbps-install -u xbps

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

Remove automatically installed packages that are no longer required as dependency (orphans)

# xbps-remove -o

List and remove specific kernel versions

# vkpurge list

# vkpurge rm 6.12.11_1

or remove all previous kernels

# vkpurge rm all

Pro Tips

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

# xbps-pkgdb -m hold linux6.18

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

Then force the update later if needed (-f, --force)

# xbps-install -Suf linux6.18

Packages to consider:

linux-firmware-amd

linux-firmware-broadcom

linux-firmware-intel

linux-firmware-network

linux-firmware-nvidia

Useful shell 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"

Package Management

X Binary Package System (XBPS) ➔ https://docs.voidlinux.org/xbps

List repositories (-L, --list-repos)

# xbps-query -L

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

# xbps-install -S Waybar

or install without syncing repos

# xbps-install Waybar

Note: Package names are case sensitive for installation purposes.

Update a package (-u, --update)

# xbps-install -u vim

Update all installed packages (-S, --sync) (-u, --update)

# xbps-install -Su

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

# xbps-install -Mun

or sync / write to disk first, and then initiate the update without actually taking action

# xbps-install -S

# xbps-install -un

Search in all available packages in configured repositories (-s, --search)

# xbps-query -Rs "window manager"

or search using regular expressions

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

or list all packages

# xbps-query -Rs ""

Search among installed packages

# xbps-query -s vim

or list all installed packages

# xbps-query -s ""

List packages only in a specified (not configured) repository (-i, --ignore-conf-repos) (-M, --memory-sync)

$ xbps-query -siM --repository https://repo.voiders.dev ""

Note: xbps-query command short option -R and long option --repository are not the same (unlike xbps-install). Only the latter takes the URL argument. [man page]

Reinstall a package (-f, --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 (-D, --download-only)

# xbps-install -D vim

Downgrade a package using local cache file (-R, --repository) (-f, --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 (-m, --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 after installation

# xbps-pkgdb -m auto vim

or during installation (-A, --automatic)

# xbps-install -A vim

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

List all installed packages with status (-l, --list-pkgs)

# xbps-query -l

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

# xbps-query -m

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

# xbps-query -H

List package orphans (-O, --list-orphans)

# xbps-query -O

Remove a package

# xbps-remove inxi

and also remove all dependencies (-R, --recursive)

# xbps-remove -R inxi

Remove orphaned packages (-o, --remove-orphans)

# xbps-remove -o

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

# xbps-remove -O

Show information about an 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 in repository

# xbps-query -R gvim

List files installed by a package (-f, --files)

# xbps-query -f vim

Show which installed package owns the file (-o, --ownedby) matching a string or regular expression

# xbps-query -o "*bin/vim*"

or using extended regular expressions

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

List package dependencies (-x, --deps)

# xbps-query -x vim

List package reverse dependencies (-X, --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 an installed package (-f, --force)

# xbps-reconfigure -f fontconfig

and dependencies (-x, --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

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

Extra Tools

xtools (Helpers for working with XBPS) ➔ https://github.com/leahneukirchen/xtools

Install xtools

# xbps-install xtools

Install a package directly from .xbps file

# xdowngrade mypackage.xbps

List installed packages by size

# xhog

List installed packages by installation date

# xilog

List installed packages not in repo (-v show version)

# xpkg -D -v

or not from remote repos

# xpkg -L -v

Reverse package search by files (-S clone repo first)

# xlocate -S

# xlocate bin/vi

Show diff between current modified configuration files in /etc and original binary packages

# xetcchanges

or for a specific conf file

# xetcchanges /etc/fstab

List programs using outdated libraries after update

# xcheckrestart

Show news messages for packages by installation date

# xnews

Bootstrap a new Void Linux installation and chroot into it

$ mkdir newinstall

# xvoidstrap newinstall/

# xchroot newinstall/

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

List all package alternatives

# xbps-alternatives -l

or only alternatives from a package (for example vi, vim)

# xbps-alternatives -l neovim

or match a group (for example 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

Install zramen and enable the 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

Suppress kernel messages on tty1

# vim /etc/sysctl.conf

kernel.printk = 3 3 3 3

# sudo sysctl -p

Workstation performance optimizations at the cost of security – disables all optional CPU vulnerability mitigations, and disables lockup detectors

# vim /etc/default/grub

GRUB_CMDLINE_LINUX_DEFAULT="mitigations=off nowatchdog"

# update-grub

Send hostname set in /etc/hostname to DHCP server

# vim /etc/dhcpcd.conf

hostname

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.

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.

Build Packages From Source

Some packages are not built and distributed in binary format by Void Linux due to large size, legal restrictions, release model, etc. These packages still have their build templates and can be locally built and installed from The Void Source Packages Collection.

void-packages ➔ https://github.com/void-linux/void-packages

Setup

Clone the entire void-packages git repository

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

or only one level (smaller, faster, if not contributing)

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

Install the 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 <pkgname>

Build

Build a package – available afterward in hostdir/binpkgs or hostdir/binpkgs/nonfree, for example google-chrome:

$ ./xbps-src pkg google-chrome

If the build fails, clean the leftovers in masterdir (successful builds get cleaned automatically)

./xbps-src clean

Install the built package (-R, --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>

Update

Keep the bootstrap packages updated to the latest version

$ ./xbps-src bootstrap-update

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

$ ./xbps-src zap

$ ./xbps-src binary-bootstrap

Update the Void packages source tree

$ cd void-packages

$ git pull

Check for new upstream releases of software from package templates

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

Update locally built packages (but first make sure all repo packages are up-to-date: sudo xbps-install -Su)

$ ./xbps-src update-sys

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

Create

Before working on a template, check for newly added and updated packages:

➔ void-updates list of packages generated daily
➔ Open pull requests submitted and awaiting approval
➔ Closed pull requests either already merged or rejected

Make a blank package template

$ xnew <pkgname>

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

Edit

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

Update checksum (-f = force file download, -i = in-place)

$ xgensum -f -i <pkgname>

Lint

$ xlint <pkgname>

Build

$ ./xbps-src pkg <pkgname>

Take inspiration for package templates from:

Arch Linux official PKGBUILD  ➔ https://gitlab.archlinux.org/archlinux/packaging/packages/

Arch User Repository PKGBUILD  ➔ https://aur.archlinux.org/packages

Alpine Linux APKGBUILD ➔ https://git.alpinelinux.org/aports/tree/main | community | testing

Automate the detection of new upstream releases via the update file, for example

void-packages/srcpkgs/<pkgname>/update

site="https://git.<sitename>/<devname>/<pkgname>/tags"

pattern="(?<!archive/)v?\K[0-9.]+(?=\.tar\.gz)"

Pattern breakdown:

(?<!archive/): A negative lookbehind that ensures the match is not preceded by the string archive/

v?: An optional literal character v, allowing for versions like 1.0 or v1.0

\K: A keep/reset operator that discards the matched text before this point from the final result, ensuring only the subsequent part is returned

[0-9.]+: Matches one or more digits or dots, capturing the version string

(?=\.tar\.gz): A positive lookahead that ensures the version number is immediately followed by the .tar.gz extension, without including the extension in the match

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

xbps-src tutorials (by meator) ➔ https://xbps-src-tutorials.github.io

Miscellaneous

XBPS wrapper providing a single command with conventional syntax
xbps ➔ https://github.com/wizetek/voidlinux

Aliases and functions to simplify common tasks

# XBPS updates inside a terminal multiplexer

upd() {

    [[ $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 bash -ic "$FUNCNAME; exec $SHELL"

    fi

}

# XBPS shorthand commands

#

# Su ➔ sync repos and update packages

# SS ➔ sync repos (and install packages)

# II ➔ install packages

# RR ➔ remove packages (recursive)

# PP ➔ list packages

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

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

alias SS='sudo xbps-install -S' # --sync

alias II='sudo xbps-install' # Install

alias If='sudo xbps-install -f' # Reinstall --force

alias CC='sudo xbps-reconfigure -f' # Reconfigure --force

alias RM='sudo xbps-remove' # Remove

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

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

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

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

alias QRS='xbps-query -RS' # Repository --show

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

alias QRs='xbps-query -Rs' # Repository --search

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

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

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

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

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

alias QRf='xbps-query -Rf' # Repository --files

alias Qo='xbps-query -o' # --ownedby

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

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

alias PV=QRS

alias PS=QRs

alias PF=QRf

alias PI='xbps-query -s ""' # List installed --search

alias PL='xbps-query -Rs "" | grep -v "^\[\*" | cut -c 1-$(tput cols)' # List available, Repository --search

alias PP='xbps-query -Rs ""' # List all, Repository --search

alias PH='sudo xbps-pkgdb -m hold' # Hold --mode

alias PU='sudo xbps-pkgdb -m unhold' # Unhold --mode

alias PA='sudo xbps-pkgdb -m auto' # Set automatically installed --mode

alias PM='sudo xbps-pkgdb -m manual' # Set manually installed --mode

# runit shortcuts

alias svavailable='ls -1 /etc/sv/'

alias svlist='ls -1 /var/service/'

alias svstatus='sudo sv status /var/service/*'

svenable(){ sudo ln -s /etc/sv/${1} /var/service/; }

svdisable(){ sudo unlink /var/service/${1}; }