Void is an independent Linux distribution developed in the spare time of a handful of developers. We do this for fun and hope that our work will be useful to others. Void is generally considered stable enough for daily use, and breaking changes are few and far between.

Some things that make Void unique in the crowded world of Linux distributions include our package manager, XBPS, which is developed in-house and is extremely fast. XBPS performs checks when installing updates to ensure that libraries aren't moved to incompatible versions, thus preventing a random update from breaking your system. XBPS is developed at https://github.com/void-linux/xbps/.

Void is also set apart from other projects by our first class support of the musl C library, which focuses on standards compliance and correctness. The musl C project allows us to also build very resilient systems as it is practical to statically link certain components on our musl flavors whereas it would not be practical to do so with glibc.

Along with our support of musl C, we also use the LibreSSL libraries instead of the more traditional OpenSSL counterpart. LibreSSL developers have shown time and time again that they are dedicated to the security, quality, and maintainability of this critical library.

A final distinguishing characteristic of Void is our choice of program for init(8). Void Linux boots with smarden runit, a very small service supervision system. The small codebase of runit allows us to support a second libc without significant effort, something that would not have been possible with other options available today. You can learn more about runit on its website http://smarden.org/runit/.


Knowledge of the ancients...

This section includes the history of void, important milestones and happenings that happened, and why things are the way they are.

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:

Architecture CPU RAM Storage
x86_64-glibc EM64T 96MB 700MB
x86_64-musl EM64T 96MB 600MB
i686-glibc Pentium 4 (SSE2) 96MB 700MB

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:

Enlightenment Cinnamon LXDE LXQT MATE XFCE
Window Manager Enlightenment Window Manager Mutter (Muffin) Openbox Openbox Metacity (Macro) xfwm4
File Manager Enlightenment File Manager Nemo PCManFM PCManFM-Qt Caja Thunar
Web Browser Firefox ESR Firefox ESR Firefox ESR QupZilla Firefox ESR Firefox ESR
Terminal Terminology gnome-terminal LXTerminal QTerminal MATE terminal xfce4-Terminal
Document Viewer - - - - Atril (PS/PDF) -
Plain text viewer - - - - Pluma Mousepad
Image viewer - - GPicView LXImage Eye of MATE Ristretto
Archive unpacker - - - - Engrampa -
Other Mixer, EConnMan (connection manager), Elementary Test - LXTask (task manager), MIME type editor Screen grabber Screen grabber, file finder, MATE color picker, MATE font viewer, Disk usage analyzer, Power statistics, System monitor (task manager), Dictionary, Log file viewer Bulk 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.

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 RAM Recommended swap space Swap space if using hibernation
< 2GB 2x the amount of RAM 3x the amount of RAM
2-8GB Equal to amount of RAM 2x the amount of RAM
8-64GB At least 4GB 1.5x the amount of RAM
64GB At least 4GB Hibernation 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.

Installation Guides

Got weird hardware or an unusual setup? This is the section for guides about how to install Void on things that it doesn't usually like.


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.

Services And Daemons

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

Enabling Services

Services are enabled by simply linking them into the /var/service service directory.

# ln -s /etc/sv/<service name> /var/service/

Disabling Services

To disable them again you just remove the link.

# rm /var/service/<service name>

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

# touch /var/service/<service name>/down

Starting and Stopping

Activated services can be controlled with the sv(8) command, following commands are available and can be used like sv <command> <services...>.

  • up to start, down to stop and once to start services once.
  • pause, cont, hup, alarm, interrupt, quit, 1, 2, term and kill to send the corresponding signal.
  • start, stop, reload and restart for LSB init compatibility.

See the sv(8) manual page for further information.

Service Status

The status command can be used to retrieve the current status of one or more services. It accepts either service names or service directories, which makes it possible to use shell wildcards to retrieve the status for all activated services.

# sv status dhcpcd
run: /var/service/dhcpcd: (pid 659) 561392s
# sv status /var/service/*
run: /var/service/agetty-tty1: (pid 658) 561392s
run: /var/service/agetty-tty2: (pid 639) 561392s
run: /var/service/agetty-tty3: (pid 662) 561392s
run: /var/service/agetty-ttyS0: (pid 650) 561392s
run: /var/service/dhcpcd: (pid 659) 561392s
run: /var/service/nanoklogd: (pid 666) 561391s
run: /var/service/ntpd: (pid 665) 561391s; run: log: (pid 664) 561391s
run: /var/service/opensmtpd: (pid 661) 561392s
run: /var/service/socklog-unix: (pid 646) 561392s; run: log: (pid 645) 561392s
run: /var/service/sshd: (pid 674) 561391s
run: /var/service/udevd: (pid 660) 561392s
run: /var/service/uuidd: (pid 640) 561392s

Options and Configuration

Extra options can be passed to most services using a conf file in the service directory.

$ cat /etc/sv/sshd/run
ssh-keygen -A >/dev/null 2>&1 # Will generate host keys if they don't already exist
[ -r conf ] && . ./conf
exec /usr/bin/sshd -D $OPTS
# echo 'OPTS="-p 2222"' >>/etc/sv/sshd/conf

Another example is the wpa_supplicant service which has other available variables.

# cat /etv/sv/wpa_supplicant/run
[ -r ./conf ] && . ./conf
exec 2>&1
exec wpa_supplicant -c ${CONF_FILE:=/etc/wpa_supplicant/wpa_supplicant.conf} -i ${WPA_INTERFACE:=wlan0} ${OPTS:=-s}
# echo WPA_INTERFACE=wlp3s0 >>/etc/sv/wpa_supplicant/conf

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
# usermod -aG socklog <your username>
# ln -s /etc/sv/socklog-unix /var/service/
# ln -s /etc/sv/nanoklogd /var/service/

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


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

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

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


XXX: add example of blacklisting kernel modules for mkinitcpio

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.4.0_2                       Dynamic Kernel Modules System
[-] exfat-dkms-1.2.8_2                 Exfat kernel driver (nofuse)
[-] spl-                     Solaris Porting Layer -- userland and kernel modules (using DKMS)
[-] tp_smapi-dkms-0.42_2               IBM ThinkPad hardware functions driver
[-] virtualbox-ose-dkms-5.1.24_1       General-purpose full virtualizer for x86 hardware - kernel module sources for dkms
[-] virtualbox-ose-guest-dkms-5.1.24_1 General-purpose full virtualizer for x86 hardware - guest addition module source for dkms
[-] zfs-                     Z File System -- userland and kernel modules (using DKMS)
[-] zfs-32bit-               Z File System -- userland 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-381.22_2               NVIDIA drivers for linux (long-lived series) - DKMS kernel module
[-] nvidia304-dkms-304.135_4           NVIDIA drivers (For GeForce 5 FX, 6, 7, 8 series) - DKMS kernel module
[-] nvidia340-dkms-340.102_5           NVIDIA drivers (GeForce 8, 9, 9M, 100, 100M, 200, 300 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)


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.


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.

Brand Type Driver Package
AMD Open Source xf86-video-amdgpu
ATI Open Source xf86-video-ati
Intel Open Source xf86-video-intel
NVIDIA Open Source xf86-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.

Brand Type Model Driver Package
ATI/Radeon Proprietary catalyst
NVIDIA Proprietary 500+ nvidia
NVIDIA Proprietary 300/400 Series nvidia390
NVIDIA Proprietary GeForce8/9 + 100/200/300 Series nvidia340

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.

| Driver | |------------------------| | xf86-input-evdev | | xf86-input-joystick | | xf86-input-libinput | | xf86-input-mtrack | | xf86-input-synaptics | | xf86-input-vmmouse | | xf86-input-wacom |

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/

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.


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.

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. In normal use your traffic will be routed to the nearest mirror to you based on your IP Address. If you would like to directly use a particular mirror you can set this manually. This can also be handy if you are on a different continent than the primary mirror, or if you are not on the same continent as any officially managed mirrors.

Tier 1 mirrors

Tier 1 mirrors sync directly from the build-master and will always have the latest packages available. These repositories are maintained by the Void Linux Infrastructure Team. In rare occasions we may permit a mirror that we don’t manage to sync directly from our primary servers if there are extenuating circumstances.

Tier 2 mirrors

Tier 2 mirrors sync from a nearby tier 1 mirror when possible, but there is no guarantee of a mirror being nearby. These mirrors are not managed by Void nor do they have any specific guarantees for staleness or completeness of packages. Tier 2 mirrors are free to sync only specific architectures and exclude sub-repositories (nonfree/multilib).

Mirror List

Tier 1 mirrors

Repository Location
http://alpha.de.repo.voidlinux.org EU: Germany
http://beta.de.repo.voidlinux.org EU: Germany
http://alpha.us.repo.voidlinux.org USA: Kansas City
http://mirror.clarkson.edu/voidlinux/ USA: New York
http://mirrors.servercentral.com/voidlinux/ USA: Chicago

Tier 2 mirrors

Repository Location
http://mirror.aarnet.edu.au/pub/voidlinux/ AU: Canberra
http://ftp.swin.edu.au/voidlinux/ AU: Melbourne
http://ftp.acc.umu.se/mirror/voidlinux.eu/ EU: Sweden
https://mirrors.dotsrc.org/voidlinux/ EU: Denmark
http://www.gtlib.gatech.edu/pub/VoidLinux/ USA: Atlanta
https://void.webconverger.org APAN: Singapore
http://ftp.lysator.liu.se/pub/voidlinux/ EU: Sweden
http://lysator7eknrfl47rlyxvgeamrv7ucefgrrlhk7rouv3sna25asetwid.onion/pub/voidlinux/ EU: Sweden

Changing Mirrors

Repository files define URLs for the repository mirror used. 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 repository file in /etc/xbps.d.

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

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.

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

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

Afterwards sign one or more packages with the following command:

$ xbps-rindex --signedby "I'm Groot" --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

If you would like to contribute to the void-docs project, the repository is hosted at https://github.com/void-linux/void-docs/. 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.