Void Linux from Scratch: A Complete Install Guide

Void Linux is one of the few distributions that still feels like a blank canvas. There is no systemd, no default desktop, and no opinion about how your machine should be arranged. You get a rolling-release base, the xbps package manager, and runit for services. Everything else is your decision.

That is also why the first install can feel intimidating. The live image drops you into a text environment, and the installer asks questions that many distributions hide from you: partition layout, mount points, bootloader, locale, services.

This guide walks through the whole process on x86_64. The main path uses void-installer, the official TUI installer. After that, there is a manual chroot install for people who want to understand what the installer actually does. Both end with the same result: a bootable Void system you can build on.

Before you start: back up your data. Partitioning is destructive, and one wrong device name is enough to erase the wrong disk.

Why Void Linux

A few things make Void different from the usual suspects:

runit instead of systemd. Services are small directories with a run script. You enable one by creating a symlink in /var/service. No unit files, no systemctl, no dependency graph to debug.
xbps. A fast binary package manager with proper dependency handling, atomic updates, and a useful query interface. It is not apt, pacman, or dnf, but it is easy to learn.
Rolling release. Install once, update forever. There are no point releases to reinstall.
glibc or musl. Void ships both. The glibc edition is the safe default. The musl edition is smaller and cleaner, but some proprietary software and a few drivers will not work.
Minimal by default. The base image has no desktop. You install exactly what you need.

For a first install, use the glibc edition. You can always try musl later in a VM.

What you need

A USB drive of at least 2 GB.
An x86_64 machine with UEFI or BIOS.
A wired connection if possible. Wireless works, but the installer's network step is simpler with Ethernet.
The current Void live image.

Download it from the official mirror:

https://repo-default.voidlinux.org/live/current/

Pick the base image if you want to build the system yourself. The xfce image includes a desktop and is convenient if you just want a working graphical system quickly. This guide assumes the base image.

Verify the image

Do not skip this. The directory contains sha256sum.txt and sha256sum.sig. The signature proves that the checksum file is authentic; the checksum proves that the ISO was not corrupted.

On an existing Void system, the release keys are in the void-release-keys package:

sudo xbps-install -S void-release-keys minisign
minisign -V -p /usr/share/void-release-keys/void-release-YYYYMMDD.pub \
  -x sha256sum.sig -m sha256sum.txt
sha256sum -c sha256sum.txt --ignore-missing

Replace YYYYMMDD with the date in the image filename, for example 20250202. On another distribution, download the matching public key from the void-packages repository first, then run the same commands.

If either step fails, download the image again. Do not install from an image that does not verify.

Write the ISO to a USB drive

On Linux, find the device with lsblk and write the image directly. Make absolutely sure of= points to the whole disk, not a partition:

lsblk
sudo dd if=void-live-x86_64-YYYYMMDD-base.iso of=/dev/sdX bs=4M status=progress oflag=sync

On Windows, use Rufus in DD mode, or use Ventoy and copy the ISO to the Ventoy partition. On macOS, use dd with the raw device:

sudo dd if=void-live-x86_64-YYYYMMDD-base.iso of=/dev/rdiskN bs=4m

Warning: dd writes without asking for confirmation. Double-check the device name. /dev/sda and /dev/sdb are one typo apart.

Boot the live image

Boot from the USB drive. If the machine refuses to boot, disable Secure Boot in the firmware settings. Void does not ship a signed shim by default, so Secure Boot will block the live image on most machines.

At the boot prompt, choose the default entry. Once the live environment is up, log in as:

login: root
password: voidlinux

Check UEFI or BIOS

Run:

ls /sys/firmware/efi

If the directory exists, you booted in UEFI mode. If it does not, you are in BIOS/legacy mode. This determines the partition table and bootloader setup, so check it before touching the disk.

You can also confirm the disk names:

lsblk -o NAME,SIZE,TYPE,FSTYPE,MOUNTPOINTS

Throughout this guide I use /dev/nvme0n1 for an NVMe disk and /dev/sda for a SATA disk. Replace them with your actual device.

Get the network up

The installer has a network step, but it is easier to fix connectivity before starting. For Ethernet, DHCP is usually enough:

ip link
dhcpcd
ping -c 3 repo-default.voidlinux.org

For wireless, use wpa_supplicant interactively:

ip link
wpa_supplicant -B -i wlan0 -c <(wpa_passphrase "SSID" "password")
dhcpcd wlan0

Replace wlan0 and the SSID with your own values. If ping is missing, iputils may not be installed on the image; curl or the installer itself can still confirm connectivity.

Plan the disk layout

Void does not impose a partition scheme. For a normal UEFI install, two partitions are enough:

Partition	Size	Type	Mount point
`/dev/nvme0n1p1`	512 MB	EFI System	`/boot/efi`
`/dev/nvme0n1p2`	Rest of disk	Linux filesystem	`/`

If you want swap, add a third partition. A common choice is 2–8 GB, or equal to your RAM if you plan to hibernate:

Partition	Size	Type	Mount point
`/dev/nvme0n1p3`	2–8 GB	Linux swap	swap

For BIOS, the layout is simpler: one bootable Linux partition for /, plus optional swap. If you use GPT on a BIOS machine, GRUB also needs a small 1 MB "BIOS boot" partition.

A few practical notes:

The ESP is usually mounted at /boot/efi, not /boot. Void keeps kernels in /boot and the EFI binaries in /boot/efi.
ext4 is a good default. XFS and Btrfs work too, but add complexity you do not need on a first install.
If the disk previously had Windows, make sure you are not deleting the Windows EFI partition unless you intend to.

Install with void-installer

Start the installer as root:

void-installer

The interface is keyboard-driven. Use the arrow keys to move, Enter to select, and Tab to move between buttons.

Keyboard

Pick your keymap. For a standard US keyboard, us is correct. For an Indonesian layout, us is still the usual choice unless you specifically use an regional variant.

Network

Select your interface and enable DHCP. For wireless, provide the SSID, encryption type (wpa), and password.

If this step fails, exit the installer, fix the connection with wpa_supplicant and dhcpcd as shown above, then start void-installer again.

Source

Choose Network to install the latest packages from the repository. This is the right choice for almost everyone, and it avoids shipping an install that is already months behind.

Choose Local only if you have no network, or if you are installing the desktop environment from the Xfce image. The Void documentation explicitly warns that the Xfce image must use Local.

Hostname

Use a short, lowercase name with no spaces, for example voidbox or thinkpad.

Locale

This screen only appears on glibc. Pick en_US.UTF-8 if you want a predictable English system, or an Indonesian locale such as id_ID.UTF-8 if you prefer localized messages. You can change it later in /etc/locale.conf.

Timezone

Choose your region. For Indonesia that is usually:

Asia/Jakarta for WIB
Asia/Makassar for WITA
Asia/Jayapura for WIT

Root password

Set a root password. This is the recovery account, so keep it somewhere safe.

User account

Create your daily user. The installer adds it to the wheel group and configures sudo access. Pick a login name without spaces or uppercase letters, and set a password.

Bootloader

Select the disk, not a partition. For example, choose /dev/nvme0n1, not /dev/nvme0n1p1. GRUB is installed to the disk's boot record or EFI partition depending on the firmware mode.

You can also choose none and install a bootloader manually later, but that is unnecessary for a normal install.

Partition

Select the disk and the installer launches cfdisk. Create the layout you planned:

For UEFI, use a GPT partition table.
Create a 512 MB partition and set its type to EFI System.
Create a second partition with the remaining space and set its type to Linux filesystem.
If you want swap, create a third partition and set its type to Linux swap.
Select Write, confirm, then Quit.

Warning: The installer cannot handle LVM, LUKS, or ZFS. If you need full-disk encryption or ZFS, use the manual chroot path and follow the official Full Disk Encryption or Root on ZFS guides.

Filesystems

For each partition, choose the filesystem and mount point:

ESP: vfat, mount at /boot/efi.
Root: ext4, mount at /.
Swap: no mount point, just initialize it.

Make sure the root partition is mounted at / and the ESP at /boot/efi. When everything is assigned, select Done.

Review and install

Use the review screen. Check the disk, the mount points, the bootloader target, and the user account. Then select Install.

The installer creates the filesystems, installs the base system, generates the initramfs, and installs GRUB. When it finishes, remove the USB drive and reboot.

The manual way: install via chroot

The installer is fine, but it hides the interesting parts. A chroot install gives you full control and is the right path for LUKS, LVM, ZFS, or unusual layouts.

This section assumes you are starting from a blank disk and a booted live image. It follows the official chroot guide, with the x86_64 glibc repository.

1. Partition and format

Create the same layout as before with cfdisk:

cfdisk /dev/nvme0n1

Then format and mount:

mkfs.vfat -F32 /dev/nvme0n1p1
mkfs.ext4 -L voidroot /dev/nvme0n1p2
mkswap /dev/nvme0n1p3
swapon /dev/nvme0n1p3

mount /dev/nvme0n1p2 /mnt
mkdir -p /mnt/boot/efi
mount /dev/nvme0n1p1 /mnt/boot/efi

If you skip swap, omit the mkswap and swapon lines.

2. Bootstrap the base system

Set the repository and architecture, copy the XBPS signing keys from the live image, and install base-system into /mnt:

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

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

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

For musl, use REPO=https://repo-default.voidlinux.org/current/musl and ARCH=x86_64-musl.

3. Generate fstab and enter the chroot

xtools provides xgenfstab and xchroot, which are available on the live image:

xgenfstab -U /mnt > /mnt/etc/fstab
cp /etc/resolv.conf /mnt/etc/resolv.conf
xchroot /mnt /bin/bash

If those commands are missing, mount the virtual filesystems and use plain chroot:

mount --rbind /dev /mnt/dev
mount --rbind /proc /mnt/proc
mount --rbind /sys /mnt/sys
chroot /mnt /bin/bash

In that case, write /etc/fstab manually. Use blkid to get the UUIDs:

UUID=xxxx-xxxx      /boot/efi   vfat   defaults   0 2
UUID=xxxxxxxx-xxxx  /           ext4   defaults   0 1
UUID=xxxxxxxx-xxxx  none        swap   sw         0 0

4. Configure the base system

Inside the chroot, set the hostname, root password, kernel, timezone, and locale:

echo "voidbox" > /etc/hostname
passwd

xbps-install -S linux linux-firmware-network

ln -sf /usr/share/zoneinfo/Asia/Makassar /etc/localtime
echo "LANG=en_US.UTF-8" > /etc/locale.conf

Enable the locale you want in /etc/default/libc-locales, then regenerate:

sed -i 's/^#en_US.UTF-8/en_US.UTF-8/' /etc/default/libc-locales
xbps-reconfigure -f glibc-locales

Create your user and install sudo:

xbps-install -S sudo
useradd -m -G wheel -s /bin/bash void
passwd void
visudo

In visudo, make sure this line is not commented out:

%wheel ALL=(ALL:ALL) ALL

5. Install GRUB

On UEFI:

xbps-install -S grub-x86_64-efi
grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id="Void"

On BIOS, install the plain grub package and target the disk:

xbps-install -S grub
grub-install /dev/sda

Then let Void regenerate the initramfs and GRUB configuration:

xbps-reconfigure -fa

That command is important. It configures every installed package, runs dracut to build the initramfs, and generates grub.cfg.

6. Enable services before first boot

Because the new system is not running yet, enable services by linking them into the default runsvdir:

ln -s /etc/sv/dhcpcd /etc/runit/runsvdir/default/
ln -s /etc/sv/dbus /etc/runit/runsvdir/default/

If you plan to use NetworkManager instead of dhcpcd, enable NetworkManager and skip dhcpcd. Running both will cause conflicts.

7. Exit and reboot

exit
umount -R /mnt
reboot

Remove the USB drive when the machine restarts.

First boot and post-install

You should land on a text login prompt. Log in as root, then update the system:

xbps-install -Syu

Networking

For a desktop or laptop, NetworkManager is the easiest option:

xbps-install -S NetworkManager
ln -s /etc/sv/dbus /var/service/
ln -s /etc/sv/NetworkManager /var/service/
sv status NetworkManager
nmtui

nmtui gives you a text interface for connecting to Wi-Fi. If you prefer the minimal route, install and enable dhcpcd instead:

xbps-install -S dhcpcd
ln -s /etc/sv/dhcpcd /var/service/

Use one network backend, not both.

Nonfree repository and firmware

Some Wi-Fi cards, GPUs, and CPUs need firmware or microcode from the nonfree repository:

xbps-install -S void-repo-nonfree
xbps-install -S

xbps-install -S linux-firmware-network
xbps-install -S intel-ucode    # Intel CPUs
xbps-install -S amd-ucode      # AMD CPUs

Depending on your hardware, you may also want linux-firmware-amd, linux-firmware-intel, or linux-firmware-nvidia.

Seat management and audio

For a graphical session, install dbus and elogind, then enable them:

xbps-install -S dbus elogind
ln -s /etc/sv/dbus /var/service/
ln -s /etc/sv/elogind /var/service/

For audio, PipeWire is the modern default. The pipewire package pulls in WirePlumber as the session manager:

xbps-install -S pipewire alsa-pipewire

mkdir -p /etc/pipewire/pipewire.conf.d
ln -s /usr/share/examples/wireplumber/10-wireplumber.conf /etc/pipewire/pipewire.conf.d/
ln -s /usr/share/examples/pipewire/20-pipewire-pulse.conf /etc/pipewire/pipewire.conf.d/

mkdir -p /etc/alsa/conf.d
ln -s /usr/share/alsa/alsa.conf.d/50-pipewire.conf /etc/alsa/conf.d/
ln -s /usr/share/alsa/alsa.conf.d/99-pipewire-default.conf /etc/alsa/conf.d/

PipeWire runs inside your user session. Your desktop environment or window manager should start it at login. If you use a minimal window manager, add pipewire to its autostart script. You can test it with:

pipewire &
wpctl status

Graphics, fonts, and a desktop

For Xorg:

xbps-install -S mesa-dri xorg xorg-input-drivers xorg-video-drivers
xbps-install -S dejavu-fonts-ttf noto-fonts-ttf

For Wayland, install mesa-dri and a compositor such as sway. Seat management comes from elogind or seatd. NVIDIA users need the proprietary driver packages and should follow the Void NVIDIA guide.

Then install a desktop environment or window manager and a display manager if you want a graphical login. Void does not choose one for you.

Bluetooth

xbps-install -S bluez
ln -s /etc/sv/bluetoothd /var/service/
usermod -aG bluetooth void

Log out and back in so the group change applies, then pair devices with bluetoothctl. For Bluetooth audio, also install libspa-bluetooth.

xbps cheat sheet

Task	Command
Sync repository indexes	`xbps-install -S`
Install a package	`xbps-install -S package`
Update everything	`xbps-install -Syu`
Remove a package and orphans	`xbps-remove -R package`
Remove orphan dependencies	`xbps-remove -Oo`
Search packages	`xbps-query -Rs keyword`
List installed packages	`xbps-query -l`
Show package details	`xbps-query -RS package`
Reconfigure all packages	`xbps-reconfigure -fa`
Check package database	`xbps-pkgdb -a`

Two habits are worth building early: run xbps-install -S before installing anything, and run xbps-install -Syu regularly. Void is rolling release, so updates are frequent but usually small.

Troubleshooting

The machine boots straight to firmware or another OS

Check the boot order:

efibootmgr

If there is no Void entry, boot the live image again, mount the installed system, enter the chroot, and rerun grub-install and xbps-reconfigure -fa. On awkward UEFI implementations, add --removable to grub-install.

No network after boot

Check whether the service is actually running:

sv status /var/service/*

If you enabled NetworkManager, make sure dhcpcd is not also enabled. If you enabled dhcpcd, make sure NetworkManager is not. Then check the interface:

ip link
ip addr

Audio only shows a dummy output

WirePlumber is probably not running, or your user cannot access the audio device. Check:

wpctl status

Make sure pipewire starts inside your graphical session and that XDG_RUNTIME_DIR is set. Without elogind, your user also needs to be in the audio and video groups.

A program refuses to run on musl

Some proprietary binaries and drivers are built against glibc. If an application fails with missing symbols or cannot find the dynamic loader, that is usually why. The practical answer is to use the glibc edition, or run the application in a container.

The clock is wrong

Set the hardware clock from the system clock:

hwclock --systohc

Make sure the timezone link is correct:

ls -l /etc/localtime

The installer cannot do LUKS, LVM, or ZFS

That is by design. Use the chroot method and the official advanced guides. The installer is intentionally small and predictable.

Final thoughts

Void rewards people who like to understand their system. The installer is a good starting point, but the chroot install is where the distribution makes sense: a base system, a kernel, a bootloader, and a handful of services. Everything else is a package you chose.

My advice for a first install is to keep it boring. Use glibc, ext4, GRUB, and a simple two-partition layout. Get the machine booting and updating. Then experiment with musl, ZFS, encryption, or a minimal window manager once you already have a system you can recover.

Take notes during the install, especially the disk names and the services you enabled. The second install is always faster.