Void is an independent, rolling release Linux distribution, developed from scratch and not as a fork of any other distribution. There are a few features that make Void unique:

  • The XBPS package manager, which is extremely fast, developed in-house, and performs checks when installing updates to ensure that libraries are not changed to incompatible versions which can break dependencies.
  • The musl libc, which focuses on standards compliance and correctness, has first class support. This allows us to build certain components for musl systems statically, which would not be practical on glibc systems.
  • The LibreSSL fork is used instead of the mainline OpenSSL library. Developed as part of the OpenBSD project, LibreSSL is dedicated to the security, quality, and maintainability of this critical library.
  • runit is used for init(8). This allows Void to support musl as a second libc choice, which would not be possible with systemd. A side effect of this decision is an init system with clean and efficient operation, and a small code base.

Void is developed in the spare time of a handful of developers, and is generally considered stable enough for daily use. We do this for fun and hope that our work will be useful to others.


Knowledge of the ancients, grepped from the git logs themselves:

  • Sep 26 2008: first git import of void-packages
  • Aug 17 2009: first git import of xbps
  • Mar 1 2013: first musl toolchains added
  • Jul 14 2014: begin switching to LibreSSL
  • Jul 28 2014: switch from systemd to runit

How To Read The Handbook

This handbook is not an extensive guide on how to use and configure common Linux software. The purpose of this document is to explain how to install, configure, and maintain Void Linux systems, and to highlight the differences between common Linux distributions and Void.

Those looking for tips and tricks on how to configure a Linux system in general should consult upstream software documentation. Additionally, the Arch Wiki provides a fairly comprehensive outline of common Linux software configuration, and a variety of internet search engines are available for further assistance.

Reading The Manuals

While this handbook does not provide a large amount of copy and paste configuration instructions, it does provide links to the man pages for the referenced software wherever possible.

Example Commands

Examples in this guide may have snippets of commands to be run in your shell. When you see these, any line beginning with $ is run as your normal user. Lines beginning with # are run as root. After either of these lines, there may be example output from the command.


This section includes all the information you could ever want to know about the process of installing Void in the abstract. For specific guides, see the Guides subsection.

Base System Requirements

Void can be installed on very minimalist hardware, though we recommend the following minimums for most installations:

i686-glibcPentium 4 (SSE2)96MB700MB

Note: Flavor installations require more resources. How much more depends on the flavor.

Void is not available for i386, i486, or i586 architectures.

It is highly recommended to have a network connection available during install to download updates, but this is not required. ISO images contain installation data on-disc and can be installed without network connectivity.

Live Installers

Void provides live installer images containing a base set of utilities, an installer program, and package files to install a new Void system. These live images are also useful for repairing a system that is not able to boot or function properly.

There are x86_64 images for both glibc and musl based systems. There are also images for i686, but only glibc is supported for this architecture. Live installers are not provided for other architectures. Users of other architectures will need to use rootfs tarballs, or perform an installation manually.

Installer images

Void releases two types of images: base images and "flavor" images. Linux beginners are encouraged to try one of the more full-featured flavor images, but more advanced users may often prefer to start from a base image to install only the packages they need.

Base images

The base images provide only a minimal set of packages to install a usable Void system. These base packages are only those needed to configure a new machine, update the system, and install additional packages from repositories.

Flavor images

Each of the Void "flavor" images includes a full desktop environment, web browser, and basic applications configured for that environment. The only difference from the base images is the additional packages and services installed.

The install process for each of the flavor images is the same as the base images, except that you must select the Local source when installing. If you select Network instead, the installer will download and install the latest version of the base system, without any additional packages included on the live image.

Comparison of flavor images

Here's a quick overview of the main components and applications included with each flavor:

Window ManagerEnlightenment Window ManagerMutter (Muffin)OpenboxOpenboxMetacity (Marco)xfwm4
File ManagerEnlightenment File ManagerNemoPCManFMPCManFM-QtCajaThunar
Web BrowserFirefox ESRFirefox ESRFirefox ESRQupZillaFirefox ESRFirefox ESR
TerminalTerminologygnome-terminalLXTerminalQTerminalMATE terminalxfce4-Terminal
Document Viewer----Atril (PS/PDF)-
Plain text viewer----PlumaMousepad
Image viewer--GPicViewLXImageEye of MATERistretto
Archive unpacker----Engrampa-
OtherMixer, EConnMan (connection manager), Elementary Test-LXTask (task manager), MIME type editorScreen grabberScreen grabber, file finder, MATE color picker, MATE font viewer, Disk usage analyzer, Power statistics, System monitor (task manager), Dictionary, Log file viewerBulk rename, Orage Globaltime, Orage Calendar, Task Manager, Parole Media Player, Audio Mixer, MIME type editor, Application finder

Downloading Images

The most recent live images can be downloaded from https://alpha.de.repo.voidlinux.org/live/current/. Previous releases can be found under https://alpha.de.repo.voidlinux.org/live/, organized by date.

Verify images

Each image releases's directory contains two files used to verify the image(s) you download. First, there is a sha256sums.txt file containing image checksums to verify the integrity of the downloaded images. Second is the sha256sums.txt.sig file, used to verify the authenticity of the checksums.

We want to verify both the image's integrity and authenticity, so for this, we want to download both files:

$ wget http://alpha.de.repo.voidlinux.org/live/current/sha256sums.txt{,.sig}

Verify image integrity

You can verify the integrity of a downloaded file using sha256sum(1) with the sha256sums.txt file we downloaded above. The following sha256sum command will check (-c) the integrity of only the image(s) you've downloaded:

$ sha256sum -c --ignore-missing sha256sums.txt
void-live-x86_64-musl-20170220.iso: OK

This verifies that the image is not corrupt.

Verify image authenticity

To verify that the downloaded sha256sums.txt file is the one that the Void Linux maintainers published and signed, we use PGP. For this, we need the sha256sums.txt.sig downloaded above.

The file is signed with the Void Images key:

  • Signer: Void Linux Image Signing Key <images@voidlinux.eu>
  • KeyID: B48282A4
  • Fingerprint: CF24 B9C0 3809 7D8A 4495 8E2C 8DEB DA68 B482 82A4

You can use gpg(1) to receive the key from a keyserver using the command in the following example. You can also download it from https://alpha.de.repo.voidlinux.org/live/current/void_images.asc.

$ gpg --recv-keys B48282A4
gpg: requesting key B48282A4 from hkp server keys.gnupg.net
gpg: key B48282A4: public key "Void Linux Image Signing Key <images@voidlinux.eu>" imported
gpg: no ultimately trusted keys found
gpg: Total number processed: 1
gpg:               imported: 1  (RSA: 1)

With the key stored locally, you can use gpg(1) verify the signature of sha256sums.txt using the sha256sums.txt.sig file:

$ gpg --verify sha256sums.txt.sig 
gpg: assuming signed data in `sha256sums.txt'
gpg: Signature made Sat Oct  7 17:18:35 2017 CDT using RSA key ID B48282A4
gpg: Good signature from "Void Linux Image Signing Key <images@voidlinux.eu>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg:          There is no indication that the signature belongs to the owner.
Primary key fingerprint: CF24 B9C0 3809 7D8A 4495  8E2C 8DEB DA68 B482 82A4

This verifies that the signature for the checksums is authentic. In turn, we can assert that the downloaded images are also authentic if their checksums match.

Prepare Installation Media

After downloading a live image, it must be written to bootable media, such as a USB drive, SD card, or CD/DVD.

Create a bootable usb drive or SD card on Linux

Identify the Device

Before writing the image, identify the device you'll write it to. You can do this using fdisk(8). After connecting the storage device, identify the device path by running:

# fdisk -l
Disk /dev/sda: 7.5 GiB, 8036286464 bytes, 15695872 sectors
Disk model: Your USB Device's Model
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes

In the example above, the output shows the USB device as /dev/sda. On Linux, the path to the device will typically be in the form of /dev/sdX (where X is a number) for USB devices, /dev/mmcblkX for SD cards, or other variations depending on the device. You can use the model and size (7.5GiB above, after the path) to identify the device if you're not sure what path it will have.

Once you've identified the device you'll use, ensure it's not mounted by unmounting it with umount(8):

# umount /dev/sdX
umount: /dev/sdX: not mounted.

Write the live image

The dd(1) command can be used to copy a live image to a storage device. Using dd, write the live image to the device:

Warning: this will destroy any data currently on the referenced device. Exercise caution.

# dd bs=4M if=/path/to/void-live-ARCH-DATE-VARIANT.iso of=/dev/sdX
90+0 records in
90+0 records out
377487360 bytes (377 MB, 360 MiB) copied, 0.461442 s, 818 MB/s

dd won't print anything until it's completed (or if it failed), so depending on the device, this can take a few minutes or longer.

Finally, ensure all data is flushed before disconnecting the device:

$ sync

The number of records, amount copied, and rates will all vary depending on the device and the live image you chose.

Burning to a CD or DVD

Any disk burning application should be capable of writing the .iso file to a CD or DVD. The following free software applications are available (cross-platform support may vary):

Note: with a CD or DVD, live sessions will be less responsive than with a USB or hard drive.

Partitioning notes

Partitioning for a modern Linux distribution is generally very simple, however the introduction of GPT and UEFI booting does bring new complexity to the process. When creating your new partition table you will need a partition for the root filesystem, along with a swap partition and possibly another partition or two to facilitate booting, if required.

Note that if the disk has already been initialised, the top of the cfdisk screen will show the partition layout already present: Label: dos for the MBR scheme, Label: gpt for the GPT scheme. If you just want to erase the partition table before starting the installer, use wipefs(8). Otherwise, you can run cfdisk(8) manually with the -z option to start with an uninitialised disk layout; cfdisk will prompt you for the label type before continuing to the main screen.

The following sections will detail the options for partition configuration.

BIOS system notes

It is recommended that you create an MBR partition table if you are using a BIOS boot system. This will limit the number of partitions you create to four. It is possible to install a GPT partition table on a BIOS system, but grub will need a special partition to boot properly.

UEFI system notes

UEFI users are recommended to create a GPT partition table. UEFI booting with grub also requires a special partition of the type EFI System with a vfat filesystem mounted at /boot/efi. A reasonable size for this partition could be between 200MB and 1GB. With this partition setup during the live image installation, the installer should successfully set up the bootloader automatically.

Swap partitions

A swap partition is not strictly required, but recommended for systems with low RAM. If you want to use hibernation, you will need a swap partition. The following table has recommendations for swap partition size.

System RAMRecommended swap spaceSwap space if using hibernation
< 2GB2x the amount of RAM3x the amount of RAM
2-8GBEqual to amount of RAM2x the amount of RAM
8-64GBAt least 4GB1.5x the amount of RAM
64GBAt least 4GBHibernation not recommended

Boot partition (optional)

On most modern systems, a separate /boot partition is no longer necessary to boot properly. If you choose to use one, remember that Void does not remove old kernels after updates by default and each image will take at least 20MB, so plan accordingly.

Other partitions

It is fine to install your system with only a large root partition, but you may create other partitions if you want. One helpful addition could be a separate partition for your /home directory. This way if you need to reinstall Void (or another distribution) you can save the data and configuration files in your home directory for your new system.

Installation Guide

Once you have downloaded a Void image to install and prepared your install media, you are ready to install Void Linux.

Note: before you begin installation, you should determine whether your machine boots using BIOS or UEFI. This will affect how you plan partitions. See Partitioning Notes for more detail.


Boot your machine from the install media you created. If you have enough RAM, there is an option on the boot screen to load the entire image into ram, which will take some time but speed up the rest of the install process.

Once the live image has booted, log in as root with password voidlinux and run:

# void-installer

The following sections will detail each screen of the installer.


Select the keymap for your keyboard; standard "qwerty" keyboards will generally use the "us" keymap.


Select your primary network interface. If you do not choose to use DHCP, you will be prompted to provide an IP address, gateway, and DNS servers.

If you intend to use a wireless connection during the installation, you may need to configure it manually using wpa_supplicant and dhcpcd manually before running void-installer.


To install packages provided on the install image, select Local. Otherwise, you may select Network to download the latest packages from the Void repository.

Note: if you are installing a desktop environment from a ''flavor'' image, you MUST choose Local for the source!


Select a hostname for your computer (that is all lowercase, with no spaces.)


Select your default locale settings. This option is for glibc only, as musl does not currently support locales.


Select your timezone based on standard timezone options.

Root password

Enter and confirm your root password for the new installation. The password will not be shown on screen.

User account

Choose a login (default void) and a descriptive name for that login. Then enter and confirm the password for the new user. You will then be prompted to verify the groups for this new user. They are added to the wheel group by default and will have sudo access.


Select the disk to install a bootloader on when Void is installed. You may select none to skip this step and install a bootloader manually after completing the installation process. If installing a bootloader, you will also be asked whether or not you want a graphical terminal for the GRUB menu.


Next, you will need to partition your disks. Void does not provide a preset partition scheme, so you will need to create your partitions manually with cfdisk(8). You will be prompted with a list of disks. Select the disk you want to partition and the installer will launch cfdisk for that disk. Remember you must write the partition table to the drive before you exit the partition editor.

UEFI users are recommended to select GPT for the partition table and create a partition (typically between 200MB-1GB) of type EFI System which will be mounted at /boot/efi.

BIOS users are recommended to choose MBR. Advanced users may use GPT but will need to create a special BIOS partition for grub to boot.

See the Partitioning Notes for more details about partitioning your disk.


Create the filesystems for each partition you have created. For each partition you will be prompted to choose a filesystem type, whether you want to create a new filesystem on the partition, and a mount point, if applicable. When you are finished, select Done to return to the main menu.

UEFI users will need to create a vfat filesystem, and mount it at /boot/efi.

Review settings

It is a good idea to review your settings before proceeding. Use the right arrow key to select the settings button and hit <enter>. All your selections will be shown for review.


Selecting Install from the menu will start the installer. The installer will create all the filesystems selected, and install the base system packages. It will then generate an initramfs and install a GRUB2 bootloader to the bootable partition.

These steps will all run automatically, and after the installation is completed successfully, you can reboot into your new Void Linux install!

Post installation

See the Post Installation guide for some tips on setting up your new system.


Everything from basic network config to where to find tuning constants.

Post Installation

This page contains a common set of tasks to take after installing Void on a new machine.


Installation media contains a snapshot of packages from the day it was made. After installing and connecting the the network, new systems should be updated:

# xbps-install -Su

This will ensure that your system has applicable security patches and software upgrades that happened after the installation media was created.

Note: XBPS must use a separate transaction to update itself. If your first update includes the package xbps, you will need to run an additional update for the rest of the system.


Void uses the runit(8) supervision suite to run system services and daemons.

Some advantages of using runit include:

  • a small code base, making it easier to audit for bugs and security issues.
  • each service is given a clean process state, regardless of how the service was started or restarted: it will be started with the same environment, resource limits, open file descriptors, and controlling terminals.
  • a reliable logging facility for services, where the log service stays up as long as the relevant service is running and possibly writing to the log.

Service directories

Each service managed by runit has an associated service directory.

A service directory requires only one file: an executable named run, which is expected to exec a process in the foreground.

Optionally, a service directory may contain:

  • an executable named check, which will be run to check whether the service is up and available; it's considered available if check exits with 0.
  • an executable named finish, which will be run on shutdown/process stop.
  • a conf file; this can contain environment variables to be sourced and referenced in run.
  • a directory named log; a pipe will be opened from the output of the run process in the service directory to the input of the run process in the log directory.

When a new service is created, a supervise folder will be automatically created on the first run.

Managing Services

Basic usage

To start, stop or restart a service:

# sv up service_name
# sv down service_name
# sv restart service_name

To get the current status of a service:

# sv status service_name

To get the current status of all enabled services:

# sv status /var/service/*

Enabling services

Void Linux provides service directories for most daemons in /etc/sv/. To enable a service, create a symlink to the service directory in /var/service:

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

This will automatically start the service. Once a service is linked it will always start on boot and restart if it stops, unless administratively downed.

To prevent a service from starting at boot while allowing runit to manage it, create a file named 'down' in its service directory:

# touch /etc/sv/service_name/down

Disabling services

To disable a service, remove the symlink to its service directory from /var/service:

# rm /var/service/service_name


The runit-void package currently supports two runlevels: single and default.

  • single just runs sulogin(8) and the necessary steps to rescue your system.
  • default, the default run level, runs all services linked in /var/service/.

Void runit directories

  • /var/service: always linked to the currently active runlevel. All entries in /var/service are considered 'active' services (and by default, are started upon linking).
  • /etc/sv: contains subdirectories for available services (usually added by XBPS).
  • /etc/runit/runsvdir: contains all available runlevels.

Configuring Services

Most services have run files which include options for configuration. These options can be set via a conf file in the service directory. This allows service customisation without modifying the service directory provided by the relevant package.

To make more complex customisations than provided by default, edit the service.

Editing services

To edit a service, first duplicate its service directory under a different name:

# cp -aR /etc/sv/service_name /etc/sv/service_name_edited

The contents of the duplicated directory can then be edited as needed, for example, by using vi(1):

# vi /etc/sv/service_name_edited

After editing, the old service should then be stopped, disabled and replaced with the new one:

# sv down service_name
# rm /var/service/service_name
# ln -s /etc/sv/service_name_edited /var/service/

Services and Daemons

This section provides information about configuring specific services.

Per-User Services

Sometimes it would be nice to have user-specific runit services. Services that, for example, open an ssh tunnel as your current user, run a virtual machine, or regularly run daemons on your behalf. The most common way to do this to ask a system-level runsv daemon to start a runsvdir daemon as your user for your personal service directory.

Create a service as /etc/sv/$username/run with the below contents:


UID=$(pwd -P)

if [ -d "/home/${UID}/service" ]; then
	chpst -u"${UID}" runsvdir /home/${UID}/service

Then you can create runit services and symlink them under ${HOME}/service and then runit will take care of starting and restarting those services for you.

One important caveat: if any services you have need group permissions instead of just your user permissions, you will want to append those groups in a colon separated list to your username, such as /etc/sv/anon:void1:void2:void3/run instead of just /etc/sv/anon/run.


Void Linux comes without a default cron daemon, you can choose one of multiple cron implementations, by installing the package and enabling the system service.

Available choices include cronie, dcron, fcron and more.

As alternative to the standard cron implementations you can use something like snooze or runwhen which go hand in hand with service supervision.



The default installation comes with no syslog daemon, there are different implementations available.


socklog is the implementation from the runit(8) author and Void Linux provides a package with some basic configuration for it, this makes it a good choice if you don't know which one to choose.

# xbps-install -S socklog-void
# ln -s /etc/sv/socklog-unix /var/service/
# ln -s /etc/sv/nanoklogd /var/service/

The logs are saved to /var/log/socklog/ into different subdirectories.

Reading logs limited to root and users part of the socklog group. Users can be added to the group to be able to read logs:

# usermod -aG socklog <your username>

Other syslog daemons

Other syslog implementations like rsyslog and metalog are available in the package repository too.


Disabling default ttys

Void Linux enables agetty(8) services for the ttys 1 to 6 by default.

To disable agetty services remove the service symlink and create a down file in the agetty service directory to avoid that updates of the runit-void package re-enable the service.

# rm /var/service/agetty-tty6
# touch /etc/sv/agetty-tty6/down


Changing users default shell

The default shell for users can be changed with the chsh(1) tool.

$ chsh -s /bin/bash <user name>

Make sure to use the same path to the shell as its in /etc/shells or listed by the chsh(1) list command.

A list of available installed shells can be retrieved with the chsh(1) list command.

$ chsh -l

Following packages are available in the package repository and provide usable shells.

  • bash
  • dash
  • elvish
  • es
  • fish-shell
  • heirloom-sh
  • ion
  • ksh
  • loksh
  • mksh
  • posh
  • rc
  • tcsh
  • xonsh
  • yash
  • zsh



hashboot hashes all files in /boot and the MBR to check them during early boot. It is intended for when the root partition is encrypted but not the boot partition. The checksums and a backup of the contents of /boot are stored in /var/lib/hashboot by default. If a checksum doesn't match, there is the option to restore the file from backup.

If there is a core- or libreboot bios, hashboot can check bios for modifications too.


# xbps-install -S hashboot

To verify BIOS, flashrom needs to be installed, too.


After installation it is important to run

# hashboot index

to create the configurationfile and generate the index of the chosen options.

If this is not run after installation, next boot will stop with an emergency shell.

Possible options as KEY=VALUE in /etc/hashboot.cfg:

  • SAVEDIR The checksums and the backup are stored here.
  • CKMODES 001=MBR, 010=files, 100=BIOS. (eg. 101 to verify MBR and BIOS)
  • MBR_DEVICE Device with the MBR on it.
  • PROGRAMMER Use this programmer instead of "internal". Will be passed to flashrom.


For a special programmer for flashrom (eg. "internal:laptop=force_I_want_a_brick"), the following must be set in /etc/hashboot.cfg:



  • Run hashboot index to generate checksums and a backup for /boot and MBR
  • Run hashboot check to check /boot and MBR
  • Run hashboot recover to replace corrupted files with the backup


Kernel series

Void Linux provides many kernel series in the default repository,

$ xbps-query --regex -Rs '^linux[0-9.]+-[0-9._]+'
[-] linux3.16-3.16.63_1          The Linux kernel and modules (3.16 series)
[-] linux3.18-3.18.124_1         The Linux kernel and modules (3.18 series)
[-] linux4.14-4.14.98_1          The Linux kernel and modules (4.14 series)
[*] linux4.19-4.19.25_1          The Linux kernel and modules (4.19 series)
[-] linux4.20-4.20.12_1          The Linux kernel and modules (4.20 series)
[-] linux4.4-4.4.176_1           The Linux kernel and modules (4.4 series)
[-] linux4.9-4.9.160_1           The Linux kernel and modules (4.9 series)

The linux meta package which is installed by default depends on one of the kernel packages, usually the latest mainline kernel that works with all dkms modules.

Removing old kernels

When updating the kernel, old versions are left behind in case it is neccessary to roll back to an older version. Over time, many old kernel version accumulate and make updating dmks modules take a long time. Thus, it may be advisable to clean old kernels from time to time.

Removing old kernels is done using the vkpurge(8) utility. vkuprge comes pre-installed on every Void Linux system. This utility runs the necessary hooks when removing old kernels.

To list kernels that can be purged:

$ vkpurge list

To remove a specific kernel version like 3.8.2_1:

# vkpurge rm 3.8.2_1

To remove all kernels except the latest kernel of each series and the kernel that is currently booted:

# vkpurge rm all

Kernel modules

Kernel modules are typically drivers for devices or filesystems. Normally the kernel automatically loads required modules, but sometimes it may be neccessary to explicitly load modules at boot.

Loading kernel modules at boot

To load kernel modules at boot time, a .conf file like /etc/modules-load.d/virtio.conf needs to be created with the contents:

# load virtio-net

Blacklisting kernel modules

There are two different methods to blacklist kernel modules, for the initramfs and for the booted system. Some modules are loaded by the initramfs very early in the boot process, those have to be blacklisted in the initramfs.

To blacklist modules, create a .conf file like /etc/modprobe.d/radeon.conf with the contents:

blacklist radeon


To blacklist modules from being included in a dracut initramfs a .conf file needs to be created like /etc/dracut.conf.d/radeon.conf with the contents:

omit_drivers+=" radeon "

Now initramfs needs to be regenerated to make the changes take effect on the next reboot:

# dracut --force


To blacklist modules from being included in a mkinitcpio initramfs a .conf file needs to be created like /etc/modprobe.d/radeon.conf with the contents:

blacklist radeon

Now initramfs needs to be regenerated to make the changes take effect on the next reboot:

# mkinitcpio -p linux

Kernel hooks

Void Linux provides directories for kernel hooks in /etc/kernel.d/{pre-install,post-install,pre-remove,post-remove}.

Bootloaders like grub, gummiboot and lilo use those hooks to update the bootmenu. Initramfs tools like dracut and mkinitcpio use the hooks to generate initramfs files for newly installed kernels.

Dynamic Kernel Module Support (dkms)

There are kernel modules that are not part of the linux source tree that are build at install time using dkms and kernel hooks.

$ xbps-query -Rs dkms
[-] acpi_call-dkms-1.2.0_2             Kernel module allowing calls to ACPI methods through /proc/acpi/call
[-] dkms-2.7.1_1                       Dynamic Kernel Modules System
[-] exfat-dkms-1.2.8_5                 Exfat kernel driver (nofuse)
[-] lttng-modules-dkms-2.10.9_2        LTTng modules provide Linux kernel tracing capability
[-] openrazer-driver-dkms-2.5.0_1      Kernel driver for Razer devices (DKMS-variant)
[-] rtl8812au-dkms-20190731_1          Realtek 8812AU/8821AU USB WiFi driver (DKMS)
[-] rtl8822bu-dkms-20190427_1          Realtek 8822BU USB WiFi driver (DKMS)
[-] spl-0.7.13_1                       Solaris Porting Layer -- userland and kernel modules (using DKMS)
[-] tp_smapi-dkms-0.43_1               IBM ThinkPad hardware functions driver
[-] vhba-module-dkms-20190410_1        Virtual (SCSI) HBA module used by cdemu
[-] virtualbox-ose-dkms-6.0.10_1       General-purpose full virtualizer for x86 hardware - kernel module sources for dkms
[-] virtualbox-ose-guest-dkms-6.0.10_1 General-purpose full virtualizer for x86 hardware - guest addition module source for dkms
[-] zfs-0.8.1_1                        Z File System -- userland, pyzfs, and kernel modules (using DKMS)
[-] zfs-32bit-0.8.1_1                  Z File System -- userland, pyzfs, and kernel modules (using DKMS) (32bit)
[-] broadcom-wl-dkms-    Broadcom proprietary wireless drivers for Linux - DKMS kernel module
[-] catalyst-dkms-15.302_2             AMD catalyst driver 15.12 for Linux - DKMS kernel module
[-] nvidia-dkms-430.14_2               NVIDIA drivers for linux - DKMS kernel module
[-] nvidia340-dkms-340.107_3           NVIDIA drivers (GeForce 8, 9, 9M, 100, 100M, 200, 300 series) - DKMS kernel module
[-] nvidia390-dkms-390.116_3           NVIDIA drivers (GeForce 400, 500 series) - DKMS kernel module



Kernel command line arguments can be added through the grub bootloader by editing /etc/default/grub and changing the GRUB_CMDLINE_LINUX_DEFAULT variable and then regenerating the grub configuration.

# vi /etc/default/grub
# grub-mkconfig -o /boot/grub/grub.cfg


Dracut can be configured to add additional cmdline arguments to the kernel by creating a configuration file and regenerating the initramfs, make sure to reconfigure the right kernel version like linux4.12 as example.

# mkdir -p /etc/dracut.conf.d
# echo 'kernel_cmdline+="<extra cmdline arguments>"' >> /etc/dracut.conf.d/cmdline.sh
# xbps-reconfigure -f linux4.12


Network configuration in Void Linux can be done with different methods. The default installation comes with the dhcpcd(8) service enabled.

Interface Names

In newer versions udev changed the well known traditional linux naming scheme (eth0, eth0, wlan0, ...).

This behaviour can be reverted by adding net.ifnames=0 to the kernel cmdline.

Static Configuration

A static network in Void Linux can be configured with ip(8).

A simple way to configure the static network at boot is to add the necessary ip(8) commands to the /etc/rc.local file.

# Static IP configuration via iproute
ip link set dev eth0 up
ip addr add brd + dev eth0
ip route add default via


To run dhcpcd(8) on all interfaces you can enable the dhcpcd service.

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

If you want to run dhcpcd just on a specific interface you can use the dhcpcd-eth0 service if this matches your interface name. Otherwise you can just copy dhcpcd-eth0 and change it to match your interface.

$ ip link show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp3s0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP mode DEFAULT group default qlen 1000
        link/ether ff:ff:ff:ff:ff:ff brd ff:ff:ff:f
# cp -R /etc/sv/dhcpcd-eth0 /etc/sv/dhcpcd-enp3s0
# sed -i 's/eth0/enp3s0/' /etc/sv/dhcpcd-enp3s0/run
# ln -s /etc/sv/dhcpcd-enp3s0 /var/service/

For more information on configuring dhcpcd see dhcpcd.conf(5)

Firewall with iptables

The iptables package is installed by default on the base system, but not activated.

Firewall rules

Two rulesets are already installed in the /etc/iptables directory:

$ ls /etc/iptables

Adjusting the rules

You can take the simple_firewall.rules file as a basis, copy it, then modify the copy according to your needs.

$ cd /etc/iptables
# cp simple_firewall.rules iptables.rules
# vi iptables.rules

Applying the rules

iptables should not be activated as a runit service. The runit services start in parallel, so the web service might start before the iptables rules are loaded.

Instead, add these lines to /etc/rc.local to import the rules from /etc/iptables/iptables.rules:

if [ -e /etc/iptables/iptables.rules ]; then
  iptables-restore /etc/iptables/iptables.rules

Reboot, and check the active firewall rules:

# iptables -L

IP6 firewall rules

As described above, but work with /sbin/ip6tables-restore instead.


The wpa_supplicant package is installed by default on the base system and includes utilities to configure wireless interfaces and, more specifically, to handle wireless security protocols.

wpa_supplicant(8) is a daemon that manages wireless interfaces based on wpa_supplicant.conf(5) configuration files. wpa_passphrase(8) and wpa_cli(8) are frontends to manage the configuration files and the running service.

WEP configuration

For WEP configuration, you can just add the following lines to your device's wpa-supplicant.conf :

# Default configuration file for wpa_supplicant.conf(5).


# Add here your networks.
    wep_key0="YOUR AP WEP KEY"

WPA-PSK encryption

For WPA-PSK encryption, we must generate a pre shared key with wpa_passphrase(8). To do so, run the following command:

$ wpa_passphrase <MYSSID> <key>

You must append the output to your wpa_supplicant.conf file like so:

$ wpa_passphrase <MYSSID> <key> >> /etc/wpa_supplicant/wpa_supplicant-<device_name>.conf

The resulting file should look something like this:

# Default configuration file for wpa_supplicant.conf(5).


# Add your networks here.
    #psk="YOUR AP KEY"

Running wpa_supplicant under runit

The runit scripts checks the following options in /etc/sv/wpa_supplicant/conf.

  • OPTS: Options to be passed to the service. (Overrides any other options!)
  • CONF_FILE: Path to file to be used for configuration.
  • WPA_INTERFACE: Interface to be matched (May contain a wildcard; Defaults to all interfaces.)

If no conf file is found, the service searches for the following files in /etc/wpa_supplicant:

  • wpa_supplicant-<interface>.conf: if found, these files are bound to the named interface.
  • wpa_supplicant.conf: if found, this file is loaded and binds to all other interfaces found.

To enable the wpa_supplicant(8) service.

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


IWD (iNet Wireless Daemon) is a wireless daemon for Linux that aims to replace WPA supplicant.


Install the iwd package.

# xbps-install -S iwd

Enable the dbus and iwd services.

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

Note: To use EAP-TLS, EAP-TTLS, and EAP-PEAP based configurations, version ≥4.20 of the kernel is required. Previous kernel versions do not include the necessary cryptographic authentication modules.


IWD provides a command line client, iwctl. It can be used to add, remove, and configure network connections; running it produces an interactive prompt. To list available options, enter help.

$ iwctl

[iwd]# help
                               Available commands
  Commands                                          Description

  adapter list                                      List adapters
  adapter <phy> show                                Show adapter info
  adapter <phy> set-property <name> <value>         Set property

Note: By default, only the root user and those in the wheel group have permission to operate iwctl.

Some useful commands:

[iwd]# device list                                       # List all Wi-Fi devices
[iwd]# device <interface> show                           # Display details of a Wi-Fi device 
[iwd]# station <interface> scan                          # Scan for networks
[iwd]# station <interface> get-networks                  # List networks
[iwd]# station <interface> connect <network-name>        # Connect to a network
[iwd]# station <interface> connect-hidden <network-name> # Connect to a hidden network
[iwd]# station <interface> disconnect                    # Disconnect from a network
[iwd]# known-networks list                               # List known networks
[iwd]# known-networks forget <network-name>              # Forget a known network

Note: iwctl also supports passing commands as arguments.

$ iwctl station <interface> get-networks


Consult the upstream documentation for options and examples available to configure the daemon and networks as described below.

Daemon configuration

The main configuration file is located in /etc/iwd/main.conf. If it does not exist, you may create it.

Network configuration

IWD stores information on known networks, and reads information on pre-provisioned networks from network configuration files located in /var/lib/iwd; IWD monitors the directory for changes. Network configuration filenames consist of the encoding of the SSID followed by .open, .psk, or .8021x as determined by the security type.

A simple example of a WPA2/PSK secured network configuration at /var/lib/iwd/<ssid>.psk contains the pre-shared key, and optionally the plaintext password.



NetworkManager(8) is a daemon that manages network connections on Ethernet, WiFi, and mobile broadband devices and operates as an all-in-one solution to network management. The NetworkManager package contains the basic utilities to run NetworkManager(8).

Starting NetworkManager

To enable the NetworkManager(8) daemon, first disable any other network managing services like dhcpcd, wpa_supplicant, or wicd. These services all control network interface configuration, and interfere with each other.

Also, ensure that the dbus service is enabled and running. NetworkManager(8) uses dbus to expose networking information and a control interface to clients and will fail to start without it.

Finally, enable the NetworkManager(8) service:

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

Configuring NetworkManager

The NetworkManager package includes a command line tool, nmcli(1), and a Text User Interface, nmtui(1) to control network settings.

There are many other front-ends to NetworkManager(8), including nm-applet for system trays, nm-plasma for KDE Plasma, and a built in network configuration tool in GNOME.

Eduroam with NetworkManager

Eduroam is a roaming service providing international, secure Ad-Hoc internet access at universities and other academic institutions. More information can be found here.


Make sure the NetworkManager and D-Bus services are running and enabled. Then install the python3-dbus package.


Download the correct eduroam_cat installer for your university from here and execute it. It'll provide a user interface guiding you through the process.


ConnMan(8) is a daemon that manages network connections, is designed to be slim and to use as few resources as possible. The connman package contains the basic utilities to run ConnMan(8).

Starting ConnMan

To enable the ConnMan(8) daemon, first disable any other network managing services like dhcpcd, wpa_supplicant, or wicd. These services all control network interface configuration, and interfere with each other.

Finally, enable the ConnMan(8) service:

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

Configuring ConnMan

The connman package includes a command line tool, connmanctl(1) to control network settings. If you do not provide any commands connmanctl(1) starts as an interactive shell.

There are many other front-ends to ConnMan(8), including connman-ui for system trays, connman-gtk for GTK, cmst for QT and connman-ncurses for ncurses based UI.

Preventing DNS overides by ConnMan

Create /etc/sv/connmand/conf with the following content:



This section details the manual installation and configuration of the Xorg display server and common related services and utilities. If you would just like to install a full desktop environment, it is recommended to try one of the flavor images


Void provides a comprehensive xorg package which installs the server and all of the free video drivers, input drivers, fonts, and base applications. This package is a safe option, and should be adequate for most systems which don't require proprietary video drivers.

If you would like to select only the packages you need, the xorg-minimal package contains the base xorg server only. If you install only xorg-minimal, you will likely need to install a font package (like xorg-fonts), a terminal emulator (like xterm), and a window manager to have a usable graphics system.

Video Drivers

Void provides both open-source and proprietary (non-free) video drivers.

Open Source Drivers

The open source drivers are installed with the xorg package by default, or may be installed individually if the xorg-minimal was installed. Below is a table of device brands and their driver packages.

BrandTypeDriver Package
AMDOpen Sourcexf86-video-amdgpu
ATIOpen Sourcexf86-video-ati
IntelOpen Sourcexf86-video-intel
NVIDIAOpen Sourcexf86-video-nouveau

Note: Fourth generation intel users may want to use the default xorg driver, rather than installing xf86-video-intel driver package. For more information, see the Arch wiki page.

Proprietary Video Drivers

Void also provides proprietary video drivers, which are available in the non-free repository.

BrandTypeModelDriver Package
NVIDIAProprietary300/400 Seriesnvidia390
NVIDIAProprietaryGeForce8/9 + 100/200/300 Seriesnvidia340

Input Drivers

A number of input drivers are available for Xorg. If xorg-minimal was installed and a device is not responding, or behaving unexpectedly, a different driver may correct the issue. These drivers can grab everything from power buttons to mice and keyboards.


Xorg config

Although Xorg normally auto-detects drivers and configuration is not needed, a config for a specific keyboard driver may look something like a file /etc/X11/xorg.conf.d/30-keyboard.conf with the contents:

Section "InputClass"
  Identifier "keyboard-all"
  Driver "evdev"
  MatchIsKeyboard "on"

Session and Seat Management

Session and seat management is not necessary for every setup, it is used to provide device access on the fly for the currently active user session.

For desktop environments like Gnome, elogind is necessary.


Install ConsoleKit2 and activate its service. Ensure bothe the dbus and the cgmanager services are activated too.

# xbps-install -S ConsoleKit2
# ln -s /etc/sv/dbus /var/service/
# ln -s /etc/sv/cgmanager /var/service/
# ln -s /etc/sv/consolekit /var/service/

If you don't use a display manager, or your display manager doesn't start a ConsoleKit2 session on its own, you need to start a ConsoleKit2 session from your .xinitrc. ConsoleKit2 comes with a xinitrc.d script (/etc/X11/xinit/xinitrc.d/90-consolekit) which sets the STARTUP variable to the appropriate way to start the session.

The following .xinitrc script sources all scripts in /etc/X11/xinit/xinitrc.d and starts the window manager of your choice with a session.

# ~/.xinitrc
# Executed by startx (run your window manager from here)

if [ -d /etc/X11/xinit/xinitrc.d ]; then
  for f in /etc/X11/xinit/xinitrc.d/*; do
    [ -x "$f" ] && . "$f"
  unset f

exec $STARTUP <window manager>


elogind(8) is a standalone version of systemd-logind, a service to manage user logins. Install the elogind package:

# xbps-install -S elogind


Audio setup

To setup audio on your Void Linux system you have to decide if you want to use PulseAudio or just alsa.

Some applications require PulseAudio, especially closed source programs.


Install the alsa-utils package make sure your user is part of the audio group to access audio devices.

# xbps-install -S alsa-utils
# usermod -a -G audio <username>

The alsa-utils package comes with the system service /etc/sv/alsa which can be activated to save and restore the state of alsa controls like the volume at shutdown and boot respectively.

If the soundcard you want to use is not the default you can either use kernel module options or the alsa config to change the default card.

The current module order can be retrieved from the procfs filesystem.

$ cat /proc/asound/modules
 0 snd_hda_intel
 1 snd_hda_intel
 2 snd_usb_audio

To use the kernel module options you can create a file like /etc/modprobe.d/alsa.conf with following content.

options snd_usb_audio index=0

Alternatively using the alsa configuration file /etc/asound.conf or the per-user configuration file ~/.asoundrc to set a different card as the default.

defaults.ctl.card 2;
defaults.pcm.card 2;


PulseAudio depends on a dbus system daemon, make sure its enabled.

# xbps-install -S alsa-utils pulseaudio
# ln -s /etc/sv/dbus /var/service/

For applications which use ALSA directly and don't support PulseAudio, the alsa-plugins-pulseaudiopackage can be installed to make them use PulseAudio through ALSA.

# xbps-install -S alsa-plugins-pulseaudio

The PulseAudio package comes with a services file, which is not necessary in most setups and the PulseAudio maintainers discourage using a system-wide setup. Instead, PulseAudio will automatically start when needed.

There are different methods that work with PulseAudio to allow access to the audio devices, the simplest one is to just the audio group alternatively you can use a session manager, like elogind or ConsoleKit2.


Install the sndio package and enable the sndiod(8) service.

# xbps-install -S sndio
# ln -s /etc/sv/sndiod /var/service/


The service can be configured by adding sndiod(8) flags to the OPTS variable in the service configuration file (/etc/sv/sndiod/conf).

Default device

sndiod(8) uses the first alsa device by default. To use another alsa device for sndios default device snd/0 add the flags to use use specific devices to the service configuration file.

# echo 'OPTS="-f rsnd/Speaker"' >/etc/sv/sndiod/conf

Use the -f flag to chooses a device by its alsa device index or its alsa device name.

Volume control

The master and per application volume controls are controlled with MIDI messages by hardware or software.

aucatctl(1) is a tool specific to sndio to send MIDI control messages to the sndiod(8) daemon.

# xbps-install -S aucatctl

Application specific configurations


Firefox is build with sndio support, but to use it its required to set the following about:config options to use it.


To have firefox and other applications use sndio simultaneously you also have to whitelist the sndio cookie file with the following about:config options.



Mpv comes with sndio support, but to avoid it from using alsa over sndio if the device is available set the --ao=sndio command line option or add the option to mpvs configuration file.

$ echo 'ao=sndio' >> ~/.config/mpv/mpv.conf


Ensure the bluetooth controller is not blocked. Use rfkill to check whether there are any blocks and to remove soft blocks. If there is a hard block, there is likely either a physical hardware switch or an option in the BIOS to enable the bluetooth controller.

$ rfkill
0 wlan      phy0   unblocked unblocked
1 bluetooth hci0     blocked unblocked

# rfkill unblock bluetooth


Install the bluez package.

# xbps-install -S bluez

Enable the bluetoothd and dbus services.

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

Add your user to the bluetooth group and restart the dbus service, or simply reboot the system. Note that restarting the dbus service may kill processes making use of it.

# usermod -a -G bluetooth $USER
# sv restart dbus

Note: To use an audio device such as a wireless speaker or headset, ALSA users need to install the bluez-alsa package, while PulseAudio users do not need any additional software.


Manage bluetooth connections and controllers using bluetoothctl. It uses a command line interface; to find out what commands are available, enter help. To exit, enter exit or quit.

$ bluetoothctl

[bluetooth]# help
Menu main:
Available commands:
advertise             Advertise Options Submenu
scan                  Scan Options Submenu
gatt                  Generic Attribute Submenu
list                  List available controllers
show [ctrl]           Controller information
select <ctrl>         Select default controller
devices               List available devices
paired-devices        List paired devices

Consult the Arch Wiki page for an example on how to pair a device.

bluetoothctl also accepts taking commands from stdin.

$ echo "devices" | bluetoothctl
Agent registered
[bluetooth]# devices
Device XX:XX:XX:XX:XX:XX Mouse
Device XX:XX:XX:XX:XX:XX Keyboard
Device XX:XX:XX:XX:XX:XX Speaker
Device XX:XX:XX:XX:XX:XX Headset


The main configuration file is /etc/bluetooth/main.conf.

TeX Live

In Void, the texlive-bin package provides a basic TeX installation, including the tlmgr program. Use tlmgr to install TeX packages and package collections from CTAN mirrors. Install the gnupg package to allow tlmgr to verify TeX packages.

The texlive-bin package contains the latest TeX Live version; however, earlier versions, such as texlive2018-bin, are also available.

Configuring TeX Live

After installing TeX Live, update the value of PATH:

$ source /etc/profile

Check that /opt/texlive/<year>/bin/x86_64-linux (or /opt/texlive/<year>/bin/i386-linux) is in your PATH:

$ echo $PATH

If required, change the global default paper size:

# tlmgr paper <letter|a4>

Installing/Updating TeX packages

To install all available packages:

# tlmgr install scheme-full

To install specific packages, you can install the collection(s) including them. To list the available collections:

$ tlmgr info collections

To see the list of files owned by a collection:

$ tlmgr info --list collection-<name>

To install the collection:

# tlmgr install collection-<name>

To install a standalone package, first check if the package exists:

$ tlmgr search --global <package-name>

and then install it:

# tlmgr install <package_name>

To find the package providing a particular file (for example, a font):

$ tlmgr search --file <filename> --global

To remove a package or a collection:

# tlmgr remove <package_name>

To update installed packages:

# tlmgr update --all

For a full description, check:



CUPS (Common Unix Printing System) is the supported mechanism for connecting to printers on Void Linux. This section explains how to install and configure CUPS.

Install the CUPS package:

# xbps-install -S cups

Enable the CUPS service:

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

Wait until the service is marked available:

# sv status cupsd

Installing Printing Drivers

If the printer is being accessed over the network and supports PostScript or PCL, CUPS alone should be sufficient. However, additional driver packages are necessary for local printer support. The cups-filters package provides driver support for CUPS; it can be installed by running:

# xbps-install -S cups-filters

Depending on the hardware in question, additional drivers may be necessary.

Some CUPS drivers contain proprietary or binary-only extensions, these are available only in the nonfree repository and sometimes only for specific architectures.

Gutenprint drivers

Gutenprint provides support for a considerable amount of printers. These drivers can be installed by running:

# xbps-install -S gutenprint

HP drivers

Printers from Hewlett-Packard require the hplip package, which can be installed by running:

# xbps-install -S hplip

Running the following command will guide you through the driver installation process. The default configuration selections it suggests are typically sufficient.

# hp-setup -i

Brother drivers

For Brother printer support, install the foomatic drivers by running:

# xbps-install -S foomatic-db foomatic-db-nonfree

Configuring a New Printer

CUPS provides a web interface and command line tools that can be used to configure printers. Additionally, various native GUI options are available and may be better suited depending on the use case.

Web interface

To configure the printer using the CUPS web interface, navigate to http://localhost:631 in a browser. Under the "Administration" tab, select "Printers > Add Printer".

Command line

The lpadmin(8) tool may be used to configure a printer using the command line.

Graphical interface

The system-config-printer package offers simple and robust configuration of new printers. Install and invoke it:

# xbps-install -S system-config-printer
# system-config-printer

Normally this tool requires root privileges. However if you are using PolicyKit, you can install the cups-pk-helper package to allow unprivileged users to use system-config-printer.

While system-config-printer is shown here, your desktop environment may have a native printer dialog which may be found by consulting the documentation for your DE.

Manual Pages

Void packages come with manual pages and the default installation includes the mandoc manpage toolset.

The man(1) command can be used to show manual pages.

$ man 1 chroot

The mandoc toolset contains apropos(1) to search for manual pages, apropos(1) uses a database that can be updated and generated with the makewhatis(8) command.

# makewhatis -a
$ apropos chroot
chroot(1) - run command or interactive shell with special root directory
xbps-uchroot(1) - XBPS utility to chroot and bind mount with Linux namespaces
xbps-uchroot(1) - XBPS utility to chroot and bind mount with Linux namespaces
xbps-uunshare(1) - XBPS utility to chroot and bind mount with Linux user namespaces
xbps-uunshare(1) - XBPS utility to chroot and bind mount with Linux user namespaces
chroot(2) - change root directory

There are two extra packages for development and POSIX manuals that are not installed by default.

$ xbps-query -Rs man-pages
[*] man-pages-4.11_1        Linux Documentation Project (LDP) manual pages
[-] man-pages-devel-4.11_1  Linux Documentation Project (LDP) manual pages - development pages
[-] man-pages-posix-2013a_3 Manual pages about POSIX systems
# xbps-install -S man-pages-devel man-pages-posix

XBPS Package Manager

The X Binary Package System (XBPS) is a package manager designed that was designed implemented from scratch and is extremely fast. XBPS is managed by the void-linux team and developed at https://github.com/void-linux/xbps.


Like any other system it is important to keep Void Linux up to date.

In general Void should be updated with an XBPS invocation:

# xbps-install -Su

Note: XBPS must use a separate transaction to update itself. If your first update includes the package xbps, you will need to run an additional update for the rest of the system.

Restarting services

If you are installing Void in production or otherwise have long lived services, its important to note that XBPS does not restart services when they are updated. This task is left to the administrator so they can orchestrate maintenance windows, ensure reasonable backup capacity, and generally be present for service upgrades.

To find processes running different versions than are present on disk, use the xcheckrestart tool provided by the xtools package:

# xbps-install -S xtools
$ xcheckrestart
11339 /opt/google/chrome/chrome (deleted) (google-chrome)

xcheckrestart will print out the PID, path to the executable, status of the path that was launched (almost always deleted) and the process name.

xcheckrestart can and should be run as an unprivileged user.

Kernel Panic After Update

Your system likely ran out of space in /boot. XBPS installs kernels and requests that hooks such as DKMS and Dracut be run, but it doesn't remove kernels that are obsolete. This is left as a task for the administrator to permit the retention of obsolete but still booted or known working kernels.

Remove kernels with vkpurge(8).


Packages are managed by XBPS, the in-house package manager for Void Linux.

This section contains information about using the package manager and pointers to more advanced information on building packages.

General Package Management

Most general package management is done with the following commands:

  • xbps-query(1) displays information about packages installed locally, or, with the -R flag, packages contained in repositories.
  • xbps-install(1) installs and updates packages, and syncs repository indexes.
  • xbps-remove(1) removes installed packages, and can remove cached package files.

Most questions can be answered by consulting the man pages for these tools. For a more detailed overview of the X Binary Package System (XBPS), see the documentation in the xbps repository.

Downgrading to a specific package version

Via xdowngrade

The easiest way to downgrade is to use xdowngrade from the xtools package, specifying the package version you wish to downgrade to:

# xdowngrade /var/cache/xbps/pkg-1.0_1.xbps


XBPS can be used to downgrade to a package version that is no longer available in the repository index.

If the package version had been installed previously, it will be available in /var/cache/xbps/. If not, it will need to be obtained from elsewhere; for the purposes of this example, it will be assumed that the package version has been added to /var/cache/xbps/.

First add the package version to your local repository:

# xbps-rindex -a /var/cache/xbps/pkg-1.0_1.xbps

Then downgrade with xbps-install:

# xbps-install -R /var/cache/xbps/ -f pkg-1.0_1

The -f flag is necessary to force downgrade/reinstallation of an already installed package.

Building From Source

Building packages from source is an advanced topic that is best left to the documentation in the void-packages repository.

This repository can be found at http://github.com/void-linux/void-packages/.

Finding Files

To search a file in packages you can use one of two methods

The xtools package contains the xlocate utility that works like locate(1) but for all files in the void package repository.

# xbps-install -Su xtools

$ xlocate -S
From https://repo.voidlinux.org/xlocate/xlocate +
16d97bfe86...2ad1a4a8d1 master -> master (forced update)
$ xlocate fizz
nim-0.17.0_1 /usr/lib/nim/examples/fizzbuzz.nim ponysay-3.0.2_1
/usr/share/ponysay/ponies/cherryfizzy.pony ->
/usr/share/ponysay/ponies/cherrycola.pony ponysay-3.0.2_1
/usr/share/ponysay/ttyponies/cherryfizzy.pony ->
/usr/share/ponysay/ttyponies/cherrycola.pony supertux2-data-0.5.1_1

It is also possible to use xbps-query to find files, but this is strongly discouraged. It requires xbps-query to download parts of every package to find the file requested. xlocate, on the other hand, is able to query a locally cached index of all files, so no network is required to query for files.

$ xbps-query -Ro /usr/bin/xlocate
xtools-0.46_1: /usr/bin/xlocate (regular file)


Repositories are the heart of the xbps package system. Repositories can be locally or remotely available. A repository contains binary package files, which may have signatures, and a data file named $ARCH-repodata (i.e. x86_64-repodata) which may also be signed.

Note that, while local repositories do not require signatures, remote repositories must be signed.

Official Repositories

Void provides other official repositories, which are maintained by the Void project, but not installed in the default configuration:

  • debug: contains debugging symbols for packages
  • multilib: contains 32-bit libraries for 64-bit systems (glibc only)
  • multilib/nonfree: contains non-free multilib packages
  • nonfree: contains software packages with non-free licenses

The next sections provide information on installing repositories, and summaries of the different repositories offered.

Installing Repositories

Void provides official repositories that may be installed via a package. For example, to install the nonfree repository, install the package void-repo-nonfree:

# xbps-install -S void-repo-nonfree

These packages only install a repository configuration file in /usr/share/xbps.d.


Void Linux packages come without debugging symbols, if you want to debug software or look at a coredump you will need the debugging symbols. These packages are contained in the debug repo. Install the void-repo-debug package to enable this repository.

Installing debugging symbols

To get debugging symbols for packages, activate the void-repo-debug repo. Once enabled, symbols may be obtained for package by installing package-dbg.

# xbps-install -S <package>-dbg

Finding debug dependencies

The xtools package contains the xdbg utility to retrieve a list of debug packages including dependencies for a package.

$ xdbg bash
# xbps-install -S $(xdbg bash)


The multilib repository provides 32-bit packages as a compatibility layer inside a 64-bit system and is available through the package void-repo-multilib.

These repositories are only available for x86_64 systems running the glibc C library.


The multilib/nonfree repository (available through the package void-repo-multilib-nonfree) provides additional 32-bit packages which have non-free licenses. See nonfree for more information about why these packages are separated.


Void has a nonfree repository for packages that don't have free licenses. Install the void-repo-nonfree package to enable this repository.

Packages can end up in the nonfree repository for a number of reasons:

  • Non-Free licensed software with released source-code.
  • Software released only as redistributable binary packages.
  • Patented technology, which may or may not have an (otherwise) open implementation.


Void Linux maintains mirrors in several geographic regions for you to use. A fresh install will default to using the master mirror in Europe, but you may also select a different mirror manually.

Tier 1 mirrors

Tier 1 mirrors are maintained by the Void Linux Infrastructure Team. These mirrors sync directly from the build-master and will always have the latest packages available.

https://alpha.de.repo.voidlinux.org/EU: Finland
https://alpha.us.repo.voidlinux.org/USA: Kansas City
https://mirror.clarkson.edu/voidlinux/USA: New York
https://mirrors.servercentral.com/voidlinux/USA: Chicago

Tier 2 mirrors

Tier 2 mirrors sync from a nearby Tier 1 mirror when possible. These mirrors are not managed by Void and do not have any guarantees of freshness or completeness of packages, nor are they required to sync every available architecture or sub-repository.

https://mirror.aarnet.edu.au/pub/voidlinux/AU: Canberra
https://ftp.swin.edu.au/voidlinux/AU: Melbourne
https://ftp.acc.umu.se/mirror/voidlinux/EU: Sweden
https://mirrors.dotsrc.org/voidlinux/EU: Denmark
https://void.webconverger.org/APAN: Singapore
https://youngjin.io/voidlinux/APAN: South Korea
https://ftp.lysator.liu.se/pub/voidlinux/EU: Sweden
https://mirror.yandex.ru/mirrors/voidlinux/RU: Russia
https://void.cijber.net/EU: Amsterdam, NL

Tor Mirrors

Void Linux is also mirrored on the Tor network. See Using Tor Mirrors for more information.

Changing Mirrors

Each repository has a file defining the URL for the mirror used. For official repositories, these files are installed by the package manager in /usr/share/xbps.d, but if duplicate files are found in /etc/xbps.d, those values are used instead.

To modify mirror URLs cleanly, copy all the repository configuration files to to /etc/xbps.d and change the URLs in each copied repository file.

# mkdir -p /etc/xbps.d
# cp /usr/share/xbps.d/*-repository-*.conf /etc/xbps.d/
# sed -i 's|https://alpha.de.repo.voidlinux.org|<repository>|g' /etc/xbps.d/*-repository-*.conf

After changing the URLs, you must synchronize xbps with the new mirrors:

# xbps-install -S

You should see the new repository URLs while synchronizing. You can also use xbps-query to verify the repository URLs, but only after they have been synchronized:

$ xbps-query -L
 9970 https://alpha.de.repo.voidlinux.org/current (RSA signed)
   27 https://alpha.de.repo.voidlinux.org/current/multilib/nonfree (RSA signed)
 4230 https://alpha.de.repo.voidlinux.org/current/multilib (RSA signed)
   47 https://alpha.de.repo.voidlinux.org/current/nonfree (RSA signed)
 5368 https://alpha.de.repo.voidlinux.org/current/debug (RSA signed)

Remember that repositories added afterwards will also need to be changed, or they will use the default mirror.

Using Tor mirrors

Tor is an anonymising software that bounces traffic via computers all around the world. It can provide access to regular sites on the internet or to hidden sites only available on the network.

The following Void Linux Mirrors are available on the Tor Network:

http://lysator7eknrfl47rlyxvgeamrv7ucefgrrlhk7rouv3sna25asetwid.onion/pub/voidlinux/EU: Sweden

Using XBPS with Tor

XBPS can be made to connect to mirrors using Tor. These mirrors can be normal mirrors, via exit relays, or, for potentially greater anonymity, hidden service mirrors on the network.

XBPS respects the SOCKS_PROXY environment variable, which makes it easy to use via Tor.

Installing Tor

Tor can be installed using XBPS:

# xbps-install -S tor

After having installed Tor, you can start it as your own user:

$ tor

or as a system service:

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

By default, Tor will act as a client and open a SOCKS5 proxy on TCP port 9050 on localhost.

Making XBPS connect via the SOCKS proxy

XBPS reads the SOCKS_PROXY environment variable and will use any proxy specified in it. By simply setting the variable to the address and port of the proxy opened by the Tor client, all XBPS's connections will go over the Tor network.

An example upgrading your system over Tor:

# export SOCKS_PROXY="socks5://"
# xbps-install -Su

Using a hidden service mirror

To use a hidden service mirror, the default mirrors need to be overwritten with configuration files pointing to .onion-addresses that are used internally on the Tor network. XBPS allows overriding repository addresses under /etc/xbps.d.

Copy your repository files from /usr/share/xbps.d to /etc/xbps.d and replace the addresses with that of an onion service (Lysator's onion used as an example):

# mkdir -p /etc/xbps.d
# cp /usr/share/xbps.d/*-repository-*.conf /etc/xbps.d/
# sed -i 's|https://alpha.de.repo.voidlinux.org|http://lysator7eknrfl47rlyxvgeamrv7ucefgrrlhk7rouv3sna25asetwid.onion/pub/voidlinux|g' /etc/xbps.d/*-repository-*.conf

Tor provides layered end-to-end encryption so https is not necessary.

When installing packages, with SOCKS_PROXY set like the earlier example, XBPS should indicate that it is synchronising the repositories from the onion address specified in the override:

# xbps-install -S
[*] Updating `http://lysator7eknrfl47rlyxvgeamrv7ucefgrrlhk7rouv3sna25asetwid.onion/pub/voidlinux/current/aarch64/nonfree/aarch64-repodata' ...
aarch64-repodata: 4030B [avg rate: 54KB/s]
[*] Updating `http://lysator7eknrfl47rlyxvgeamrv7ucefgrrlhk7rouv3sna25asetwid.onion/pub/voidlinux/current/aarch64/aarch64-repodata' ...
aarch64-repodata: 1441KB [avg rate: 773KB/s]

Security consideration

It is advisable to set SOCKS_PROXY automatically in your environment if you are using an onion. If the setting is missing, a DNS query for the name of the hidden service will leak to the configured DNS server.

To automatically set the environment variable, add it to a file in /etc/profile.d:

# cat - <<EOF > /etc/profile.d/socksproxy.sh
export SOCKS_PROXY="socks5://"

Restricted Packages

Void offers some packages that are officially maintained, but not distributed. These packages are marked as restricted and must be built from their void-packages template locally.

Packages can be restricted from distribution by either the upstream author or Void. Void reserves the right to restrict distribution of any package for effectively any reason, massive size being the most common. Another common reason is restrictive licensing that does not allow third-party redistribution of source or binary packages.

Building manually

You can use xbps-src in the void-packages repository to build the restricted packages from templates. For instructions on building packages from templates see the void-packages documentation, and specifically the quick setup section of the README.

Remember that the building of restricted packages must be enabled explicitly by setting XBPS_ALLOW_RESTRICTED=yes in your xbps-src configuration (in the etc/conf file in the repository.)

Automated building

There is also a tool, xbps-mini-builder which automates the process of building a list of packages. The script can be called periodically and will only rebuild packages if their templates have changed.

Custom Repositories

Void supports user created repositories available locally, or remotely. This is only recommended for serving custom packages created personally, or packages from another trusted source. The Void project does not support any third party package repositories, and the use of third party software packages poses very serious security concerns, and risks serious damage your system.

Adding custom repositories

To add custom repositories create a file in /etc/xbps.d with the format:


Where <URL> is either a local directory or a URL to a remote repository.

For example, to define a remote repository:

# echo 'repository=http://my.domain.com/repo' > /etc/xbps.d/my-remote-repo.conf

Note: Remote repositories need to be signed. xbps-install(1) refuses to install packages from remote repositories if they are not signed.

Or, to define a local repository:

# echo 'repository=/path/to/repo' > /etc/xbps.d/my-local-repo.conf

Signing repositories

Remote repositories must be signed, local repositories do not need to be signed.

The xbps-rindex(1) tool is used to sign repositories. First initialize the repository metadata with signing properties (this is only required once).

The private key to sign packages needs to be a PEM encoded RSA key, the key can be generated with either ssh-keygen(1) or openssl(1) choose one of the following methods.

$ ssh-keygen -t rsa -m PEM -f private.pem
$ openssl genrsa -out private.pem

First the public part of the private key has to be added to the repository metadata, this step is only required once.

$ xbps-rindex --privkey private.pem --sign --signedby "I'm Groot" /path/to/repository/dir

Afterwards sign one or more packages with the following command:

$ xbps-rindex --privkey private.pem --sign-pkg /path/to/repository/dir/*.xbps

Note: Future packages will not be automatically signed.

Troubleshooting XBPS

Sometimes the package manager gets in a weird spot and can't fix itself without help. This section documents important fixes and things that can go wrong when working with XBPS.

Static XBPS

In rare cases, it is possible to break the system sufficiently that XBPS can no longer function. This usually happens while trying to do unsupported things with libc, but can also happen when an update contains a corrupt glibc archive or otherwise fails to unpack and configure fully.

In these cases it is possible to recover your system with a separate, statically compiled copy of XBPS.

Obtaining static XBPS

Statically compiled versions of XBPS are available in all mirrors in the static/ directory. The link below points to the static copies on the primary mirror in Germany:


Download and unpack the latest version, or the version that matches the broken copy on your system (with a preference for the latest copy).

Using static XBPS

The tools in the static set are identical to the normal ones found on most systems. The only distinction is that these tools are statically linked to the musl C library, and should work on systems where nothing else does. In systems where the platform can no longer boot, it is recommended to chroot in with Void installation media and use the static tools from there, as it is unlikely that even a shell will work correctly on the target system.


There's more to running a distribution than just writing code. This section explains how to be an active part of Void.

Usage Statistics

If you would like to contribute usage reports, the PopCorn program reports installation statistics back to the Void project. These statistics are purely opt-in, the reporting programs are not installed by default on any void systems.

PopCorn only reports which packages are installed, their version, and the host CPU architecture (the output of xuname.) This does not report which services are enabled, or any other personal information. Individual systems are tracked persistently by a random (client generated) UUID, to ensure that each system is only counted once in each 24-hour sampling period.

The data collected by PopCorn is available to view at http://popcorn.voidlinux.org

Setting up PopCorn

First, install the PopCorn package:

# xbps-install PopCorn

To run PopCorn automatically as a service, enable the sv script, which will attempt to report statistics once per day:

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

Contributing To The void-docs Project

The sources for this handbook are hosted in the void-docs repository on GitHub. If you would like to make a contribution Please follow our style guide and submit a pull-request.

Style Guide

This style guide outlines the standards for contributing to the void-docs project. The manual on https://docs.voidlinux.org is generated from an mdBook stored in the void-docs repository.


For markdown formatting, the void-docs project uses the Versioned Markdown format, and enforces use of the auto-formatter vmdfmt, which works very similarly to gofmt. Most valid markdown is accepted by the formatter. The output format is described in the project's README.

Void provides the package vmdfmt. Otherwise you may go get from the repo:

$ go get https://github.com/bobertlo/vmd/cmd/vmdfmt

To format a file you have edited, run:

vmdfmt -w <filepath>

To format the entire mdbook from the repository root, outputting a list of files modified, run:

vmdfmt -w -l <filepath>


Command code-blocks should start with a # or $ character, indicating whether the command should be run as root or a regular user, respectively.

For example:

# xbps-install -Su

And not:

$ sudo xbps-install -Su

And also not:

xbps-install -Su


Man Page Links

Including links to man page is encouraged. These links should point to their man page on https://docs.voidlinux.org, have their title section number in parenthesis, and contain no formatting in their bodies. For example: man(1), and not man(1).

Auto Links

Auto links (links with the same title as URL) should use the following notation:


They should not be formatted like this:



Filenames and directories should use kebab case when splitting words. For example the filename should be post-install.md not postinstall.md.

Words that are part of trademarks or well known package names are exempt from this rule. Examples include PulseAudio and NetworkManager which are well known by their squashed names.


Prefer the active imperative voice when writing documentation. Consider the following examples:

Now we need to install the CUPS drivers and configure them.

This version is conversational and friendlier, but contains unnecessary language that may not be as clear to an ESL reader.

Install and configure the CUPS drivers, then configure them as shown.

This version contains a clear command to act, and a follow up that shows what will be done next. It is clear both to native English speakers, ESL readers, and to translators.

Submitting Changes

Proposed changes should be submitted as pull-requests to the void-docs repository on GitHub. Please note that, unlike a wiki, submissions will be reviewed before they are merged. If any changes are required they will need to be made before a pull-request is accepted. This process is in place to ensure the quality and standards of the handbook are sustained.


To clone the repository and push changes git(1) is required, which is available as the git package.

Building the Void Handbook locally requires mdBook, which can be installed with the mdBook package on Void. At the root of the void-docs repository mdbook serve can be run to serve the docs on your localhost.


To fork the repository a github account is needed. After the account is created follow github's guide on setting up a fork.

Clone the repository onto your computer, enter it, and create a new branch:

$ git clone https://github.com/YOUR_USERNAME/void-docs.git
$ cd void-docs
$ git checkout -b <BRANCH_NAME>

After editing the file(s), commit the changes and push them to the forked repository:

$ git add <EDITED_FILE(S)>
$ git commit -m "<COMMIT_MESSAGE>"
$ git push --set-upstream origin <BRANCH_NAME>

The commit message should be in the form of section: what was changed

Pull requests should only contain a single commit. If a change is made after the initial commit git add the changed files and then run git commit --amend. The updated commit will need to be force pushed: git push --force.

If multiple commits are made they will need to be squashed into one with git rebase -i HEAD~X where X is the number of commits that need to be squashed. An editor will appear to choose which commits to squash. A second editor will appear to choose the commit message. See git-rebase(1) for more information. The updated commit will need to be force pushed: git push --force.