Installation via chroot

From Void Linux Wiki
Jump to: navigation, search

This wiki entry will explain how to perform a chroot install of Void Linux. Also commonly known as a "tarball install" or "rootfs install" depending on what terminology you're used to. Performing a chroot install allows you to get an extremely minimal system with only the core of Void Linux. Sometimes it can also be used to install Void Linux on hosting services with a recovery disc available, even if they won't allow you to upload your own Void Linux ISO.

Installs via chroot are considered more complex than regular installs, so if you're simply looking to get your first Void Linux install running, check out the regular Installation entry instead. If using UEFI, check out Installation on UEFI, via chroot

Getting started

Before you can do a chroot install, your system must already be booted off a device other than the HDD/SSD you will be installing Void onto. If possible, booting a Void Linux live USB or CD/DVD is best. If that's not available, you can use any other live media as long as it has the commands mount, wget, tar, a text editor such as nano and a tool to partition your disk, or the ability to install those tools as needed.

An ISO to create Void Linux live media can be obtained from Instructions for those images can be found on the Live Images page.

You will also need network access to perform the install. After chrooting we need to fetch multiple important packages such as the Linux kernel and the grub bootloader.

The guide will not cover setting up a graphical interface. And we'll be assuming an MBR partition table for your disk with either one or two partitions.


Once you've got your live media, boot it like normal and log into a user capable of executing root commands, or the actual root user.

After you've got a root-capable shell, you're ready to start installing.

Partitioning and formatting

The first step is to partition your disk. Running fdisk -l will list your disks. Find your disk in the list it outputs, it should look something like this:

 Disk /dev/sda: 931.5 GiB, 1000204886016 bytes, 1953525168 sectors
 Units: sectors of 1 * 512 = 512 bytes
 Sector size (logical/physical): 512 bytes / 4096 bytes
 I/O size (minimum/optimal): 4096 bytes / 4096 bytes
 Disklabel type: dos
 Disk identifier: 0x000d4385
 Device     Boot      Start        End    Sectors   Size Id Type
 /dev/sda1             4096 1949330863 1949326768 929.5G 83 Linux
 /dev/sda2       1949330864 1953525167    4194304     2G 83 Linux

Details of how to partition your disk won't be covered here, mostly because it might vary depending on the live media you're using. The Disks page contains some useful information on partitioning and filesystems to use. ext4 or xfs are the simplest choices if you're not quite sure what filesystem to use. /boot might be better off with ext2 or ext3

Note: Make sure to use an MBR partition table (Sometimes called an msdos or dos partition table). You also need to make sure that you mark your partition as bootable. If you're using a separate /boot partition, mark that one as bootable instead.

Mounting your root partition

Before we can install the tarball, we need to mount our drive. Afterwards we also have to connect /proc, /sys and /dev since the chroot environment will need these directories.

We need a mount point first of all. Run the following command to create a mount point and mount your drive:

 mkdir -p /mnt/void
 mount /dev/sdX1 /mnt/void

You can mount /boot now as well, but most people prefer, and recommend, doing it after the chroot has been performed.

Note: Make sure to replace /dev/sdX1 with your actual drive and correct partition.

Applying the rootfs/tarball

You can now go ahead and download the rootfs/tarball that we'll be using.

 cd /mnt/void
 wget <ROOTFS URL>

You can get a URL for the newest rootfs/tarball from

Pick the regular one or the musl one depending on preference, you can install either one regardless of your boot medium. If unsure, use the non-musl one or check the Musl page for extra info about differences.

After it's been downloaded, we need to unpack the rootfs/tarball. This can be done using the following command:

 tar xpf <ROOTFS FILENAME>.tar.xz --xattrs-include='*.*' --numeric-owner

Note: If the above command fails, you might need to run xbps-install -S xz and try again.

Preparing to chroot

Before we can chroot we have to prepare the environment so that it works properly. Start by doing a cd /mnt/void to be sure you're in the place we'll be chrooting.


Start by editing the file etc/resolv.conf and add the following info to get working DNS after we chroot:


Note: You can of course enter whatever DNS server you prefer here. If you're installing this on a hosted server via recovery media you might want to use your host's DNS servers (Hetzner,

Mounting system directories

Like mentioned earlier we need to mount /proc, /sys and /dev. This can be achieved with the following commands:

 mount --types proc /proc /mnt/void/proc
 mount --rbind /sys /mnt/void/sys
 mount --rbind /dev /mnt/void/dev
 mount --make-rslave /mnt/void/sys
 mount --make-rslave /mnt/void/dev


Finally we can perform the chroot into our new system. To chroot, run:

 chroot /mnt/void /usr/bin/bash

After this, only a few steps remain for a functional system.

Editing fstab

When we boot the system from disk instead of via chroot, it needs to know what disks to mount. We need to edit /etc/fstab to fix this. Each partition should have an entry like this:

 /dev/sdX1  <directory>  <filesystem>  defaults  1  2

So if you have a simple install with one large ext4 partition on /dev/sda, it would look like this:

 /dev/sda1  /  ext4  defaults  1  2

If the disk instead has a large xfs partition, as well as a /boot partition formatted with ext2, you need this:

 /dev/sda1  /      xfs   defaults  1  2
 /dev/sda2  /boot  ext2  defaults  1  2

Note: Please make sure to doublecheck all drive names, partition numbers and filesystems. Otherwise you will likely have to boot some recovery or live media again to fix fstab.

Setting a hostname

To set a correct hostname for your system, edit /etc/hostname and fill in whatever hostname you want.

Additionally, you should edit /etc/hosts and add an entry for your hostname there as well. There should already be an entries that resolve localhost, you can simply copy those lines and replace localhost with your hostname.

Updating the system

Since rootfs/tarball files are not generated all the time, packages might be outdated. So now that we've got our base set up. It's a good idea to update the system before we proceed:

 xbps-install -Su

Note: xbps might only update itself if there's an update available, if that happens, simply run the command again to upgrade the remaining packages.

Installing the Linux kernel

WARNING: If you have a separate /boot partition, mount that now with mount /dev/sdX1 /boot. Substituting with your actual partition. It does not happen automatically when using chroot.

Once you're done configuring fstab, we're only missing the kernel and a bootloader. When installing the kernel, there's two options. You can either install the regular package like so:

 xbps-install -S linux

Or you can install the LTS kernel. Which typically lacks support for more bleeding-edge hardware and features, but in return should be more stable as long as your hardware is supported:

 xbps-install -S linux-lts

Note: You can also compile your own kernel, either from scratch or using Xbps-src if that's more your cup of tea.

Installing the Bootloader

For this guide we'll be using grub since it's the simplest to set up in most situations. Start by installing the grub package:

 xbps-install -S grub

After you've installed the package, you can install grub on your drive. First, generate a config file:

 grub-mkconfig -o /boot/grub/grub.cfg

When this is done, do the actual grub installation. Assuming your drive is /dev/sda, run:

 grub-install /dev/sda

If everything worked out. You should now be able to boot your system. But there's probably some additional steps you want to take before you do so.


Before you exit chroot, you should change the root password using the passwd command.

You probably also want your own user to login with. You can do that by running useradd *USERNAME*. If you want sudo access, you should also add the user to the wheel group with usermod -aG wheel *USERNAME* and install the sudo package using:

 xbps-install -S sudo

After this, you can type visudo to edit the sudo config file. Uncomment the line that lets members of the wheel group run sudo commands.

Finally you can type exit to leave chroot, and then reboot your machine.

Congratulations! If everything went according to plan, you should now have an extremely minimal and lightweight install of Void Linux. Welcome to the Void.