About

Welcome to the Void Handbook! Please be sure to read the "About This Handbook" section to learn how to use this documentation effectively. A local copy of this handbook, in several formats, can be installed via the void-docs package and accessed with the void-docs(1) utility.

Void is an independent, rolling release Linux distribution, developed from scratch rather than as a fork, with a focus on stability over bleeding-edge. In addition, there are several 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.
• runit is used for init(8) and service supervision. 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 a core 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.

The name "Void" comes from the C literal void. It was chosen rather randomly, and is void of any meaning.

History

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

• 2008-09-26: first Git import of void-packages
• 2009-08-17: first Git import of xbps
• 2011-06-25: first systemd commit in void-packages
• 2013-03-01: first musl toolchains added
• 2014-07-14: begin switching to LibreSSL
• 2014-07-28: switch from systemd to runit
• 2015-07-09: full aarch64 support with linux4.1
• 2018-07-06: first use of Terraform for GitHub permissions, for increased transparency
• 2021-03-05: begin switching to OpenSSL

About This 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.

To search for a particular term within the Handbook, select the 'magnifying glass' icon, or press 's'.

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.

To learn how to use the man(1) man page viewer, run the command man man. It can be configured by editing /etc/man.conf; read man.conf(5) for details.

Void uses the mandoc toolset for man pages. mandoc was formerly known as "mdocml", and is provided by the mdocml package.

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.

Placeholders

Some examples include text with placeholders. Placeholders indicate where you should substitute the appropriate information. For example:

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

This means you need to substitute the text <service_name> with the actual service name.

InfraDocs

InfraDocs is the meta-manual for the Void project's systems management.

Installation

This section includes general information about the process of installing Void. For specific guides, see the "Advanced Installation" section.

Base system requirements

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

Note that Xfce installation images require more resources, and more resources may be required depending on the software being run.

Void is available on x86_64, i686, aarch64, armv7l, and armv6l architectures. Both glibc and musl editions are available on all architectures except i686, where only glibc is available. Void is not available for the i386, i486, or i586 architectures.

Before installing musl Void, please read the "musl" section of this Handbook, so that you are aware of software incompatibilities.

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-disk and can be installed without network connectivity.

Downloading installation media

The most recent live images and rootfs tarballs can be downloaded from https://repo-default.voidlinux.org/live/current/. They can also be downloaded from other mirrors. Previous releases can be found under https://repo-default.voidlinux.org/live/, organized by date.

Verifying images

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

It is necessary to verify both the image's integrity and authenticity, so it is recommended that you download both files.

Verifying digital signature

Prior to using any image, you're strongly encouraged to validate the signatures on the image to ensure they haven't been tampered with.

Current images are signed using a minisign key that is specific to the release. If you're on Void already, you can obtain the keys from the void-release-keys package, which will be downloaded using your existing XBPS trust relationship with your mirror and package signatures. You will also need a copy of minisign(1); on Void, this is provided by the minisign package.

The minisign executable is usually provided by a package of the same name, and can also be installed on Windows, even without WSL or MinGW. Binaries are also available from minisign's authors.

If you are not currently using Void Linux, it will also be necessary to obtain the appropriate signing key from our Git repository.

Once you've obtained the key, you can verify your image with the sha256sum.sig and sha256sum.txt files. First, you need to verify the authenticity of the sha256sum.txt file.

The following example demonstrates the verification of the sha256sum.txt file for the 20250202 images with minisign:

$ minisign -V -p /usr/share/void-release-keys/void-release-20250202.pub -x sha256sum.sig -m sha256sum.txt
Signature and comment signature verified
Trusted comment: This key is only valid for images with date 20250202.

Verifying image integrity

Finally, you need to verify that the checksum for your image matches the one in the sha256sum.txt file. This can be done with the sha256(1) utility from the outils package, as demonstrated below for the 20250202 x86_64 base image:

$ sha256 -C sha256sum.txt void-live-x86_64-20250202-base.iso 
(SHA256) void-live-x86_64-20250202-base.iso: OK

Alternatively, if the sha256 utility isn't available to you, you can use sha256sum(1):

$ sha256sum -c sha256sum.txt --ignore-missing
void-live-x86_64-20250202-base.iso: OK

If neither program is available to you, you can compute the SHA256 hash of the file by hand and compare it to the value contained in sha256sum.txt.

If the verification process does not produce the expected "OK" status, do not use it! Please alert the Void Linux team of where you got the image and how you verified it, and we will follow up on it.

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 images are provided for aarch64 in both glibc and musl variants, but they only support UEFI-capable devices. Live images for aarch64 do not support void-installer.

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 Xfce images. Linux beginners are encouraged to try one of the more full-featured Xfce 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.

Xfce image

The Xfce image 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 following software is included:

• Window manager: xfwm4
• File manager: Thunar
• Web Browser: Firefox
• Terminal: xfce4-terminal
• Plain text editor: Mousepad
• Image viewer: Ristretto
• Other: Bulk rename, Orage Globaltime, Orage Calendar, Task Manager, Parole Media Player, Audio Mixer, MIME type editor, Application finder

The install process for the Xfce image 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.

Accessibility support

All Void installer images support the console screenreader espeakup and the console braille display driver brltty. On UEFI-based systems, GRUB is the bootloader, and it will play a two-tone chime when the menu is available. On BIOS-based systems and UEFI systems in legacy/compatibility mode, SYSLINUX is the bootloader, and no chime is played.

Several hotkeys exist in the bootloader, which will select different entries:

• s will boot with screenreader enabled
• r will boot with screenreader enabled and will load the live ISO into RAM
• g will boot with screenreader enabled and graphics disabled
• m will enter Memtest86+ (if supported)
• f will enter the UEFI firmware setup interface (if supported)
• b will reboot the computer
• p will power off the computer

SYSLINUX requires pressing enter after pressing a hotkey.

After booting into the installer image with accessibility support enabled, if there are multiple soundcards detected, a short audio menu allows for the selection of the soundcard for the screenreader. Press enter when the beep for the desired soundcard is heard to select it.

If the Local installation source is selected in the installer, espeakup and brltty will also be installed and enabled on the installed system if enabled in the live environment.

The Xfce image also supports the graphical screenreader orca. This can be enabled by pressing Win + R and entering orca -r. Orca will also be available on the installed system if the Local installation source is selected.

Kernel Command-line Parameters

Void installer images support several kernel command-line arguments that can change the behavior of the live system. See the void-mklive README for a full list.

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 letter) 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. You can enable printing by adding status=progress to the command if using GNU coreutils dd.

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

• Brasero
• K3B
• Xfburn

It should be noted that, with a CD or DVD, live sessions will be less responsive than with a USB stick 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 initialized, 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 uninitialized 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 use a GPT partition table on a BIOS system, but GRUB will require a special partition to boot properly. This partition should be at the beginning of your disk and have a size of 1MB, with type BIOS boot (GUID 21686148-6449-6E6F-744E-656564454649). Don't create any filesystem in it. GRUB should then install itself successfully.

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.

Boot partition (optional)

On most modern systems, a separate /boot partition is no longer necessary to boot properly. If you choose to use one, note that Void does not remove old kernels after updates by default and also that the kernel tends to increase in size with each new version, so plan accordingly (e.g. /boot with one Linux 5.x x86_64 kernel and GRUB occupies about 60MB).

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.

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.

The following features are not supported by the installer script:

• LVM
• LUKS
• ZFS

Booting

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.

Keyboard

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

Network

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 choose a wireless network interface, you will be prompted to provide the SSID, encryption type (wpa or wep), and password. If void-installer fails to connect to your network, you may need to exit the installer and configure it manually using wpa_supplicant and dhcpcd before continuing.

Source

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

Warning: If you are installing the desktop environment from the Xfce image, you MUST choose Local for the source!

Hostname

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

Locale

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

Timezone

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. Default groups and their descriptions are listed here.

Login names have some restrictions, as described in useradd(8).

Bootloader

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.

Partition

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.

If using UEFI, it is recommended you 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.

If using BIOS, it is recommended you select MBR for the partition table. Advanced users may use GPT but will need to create a special BIOS partition for GRUB to boot.

The root file system needs a partition of type Linux filesystem which will be mounted at /.

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

Filesystems

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.

If using UEFI, 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.

Install

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

After booting into your Void installation for the first time, perform a system update.

Advanced Installation Guides

This section contains guides for more specific or complex use-cases.

Section Contents

• Installing Void via chroot (x86_64, i686, or aarch64)
• Installing Void with Full Disk Encryption
• Installing Void on a ZFS Root
• ARM Devices

Installation via chroot (x86_64/i686/aarch64)

This guide details the process of manually installing Void via a chroot on an x86_64, i686, or aarch64 architecture. It is assumed that you have a familiarity with Linux, but not necessarily with installing a Linux system via a chroot. This guide can be used to create a "typical" setup, using a single partition on a single SATA/IDE/USB disk. Each step may be modified to create less typical setups, such as full disk encryption.

Void provides two options for bootstrapping the new installation. The XBPS method uses the XBPS Package Manager running on a host operating system to install the base system. The ROOTFS method installs the base system by unpacking a ROOTFS tarball.

The XBPS method requires that the host operating system have XBPS installed. This may be an existing installation of Void, an official live image, or any Linux installation running a statically linked XBPS.

The ROOTFS method requires only a host operating system that can enter a Linux chroot and that has both tar(1) and xz(1) installed. This method may be preferable if you wish to install Void using a different Linux distribution.

Prepare Filesystems

Partition your disks and format them using mke2fs(8), mkfs.xfs(8), mkfs.btrfs(8) or whatever tools are necessary for your filesystem(s) of choice.

mkfs.vfat(8) is also available to create FAT32 partitions. However, due to restrictions associated with FAT filesystems, it should only be used when no other filesystem is suitable (such as for the EFI System Partition).

cfdisk(8) and fdisk(8) are available on the live images for partitioning, but you may wish to use gdisk(8) (from the package gptfdisk) or parted(8) instead.

For a UEFI system, make sure to create an EFI System Partition (ESP). The ESP should have the partition type "EFI System" (code EF00) and be formatted as FAT32 using mkfs.vfat(8).

If you're unsure what partitions to create, create a 1GB partition of type "EFI System" (code EF00), then create a second partition of type "Linux Filesystem" (code 8300) using the remainder of the drive.

Format these partitions as FAT32 and ext4, respectively:

# mkfs.vfat /dev/sda1
# mkfs.ext4 /dev/sda2

Create a New Root and Mount Filesystems

This guide will assume the new root filesystem is mounted on /mnt. You may wish to mount it elsewhere.

If using UEFI, mount the EFI System Partition as /mnt/boot/efi.

For example, if /dev/sda2 is to be mounted as / and dev/sda1 is the EFI System Partition:

# mount /dev/sda2 /mnt/
# mkdir -p /mnt/boot/efi/
# mount /dev/sda1 /mnt/boot/efi/

Initialize swap space, if desired, using mkswap(8), and enable it with swapon(8).

Base Installation

Follow only one of the two following subsections.

If on aarch64, it will be necessary to install a kernel package in addition to base-system. For example, linux is a kernel package that points to the latest stable kernel packaged by Void.

The XBPS Method

Select a mirror and use the appropriate URL for the type of system you wish to install. For simplicity, save this URL to a shell variable. A glibc installation, for example, would use:

# REPO=https://repo-default.voidlinux.org/current

XBPS also needs to know what architecture is being installed. Available options are x86_64, x86_64-musl, i686, aarch64, and aarch64-musl. For example:

# ARCH=x86_64

This architecture must be compatible with your current operating system, but does not need to be the same. If your host is running an x86_64 operating system, x86_64, x86_64-musl, or i686 architectures can be installed (whether the host is musl or glibc), but an i686 host can only install i686 distributions.

Copy the RSA keys from the installation medium to the target root directory:

# mkdir -p /mnt/var/db/xbps/keys
# cp /var/db/xbps/keys/* /mnt/var/db/xbps/keys/

Use xbps-install(1) to bootstrap the installation by installing the base-system metapackage:

# XBPS_ARCH=$ARCH xbps-install -S -r /mnt -R "$REPO" base-system