This entry attempts to walk through the basic steps required to perform a minimal Void Linux installation via a Void live image . It does not attempt to go into fine detail for every step but additional documentation may be found linked throughout this document, as well as via man pages, additional resources in the Guides section etc.

If you are installing on a UEFI system, and wish to do so in UEFI mode, then you should read the notes in the green boxes that specify instructions for UEFI systems,If you encounter any issues please refer to troubleshooting for basic troubleshooting.

Getting Started

Download the Void live image ISO from and create an installation medium.

For further information regarding the live images and system requirements, see Live Images.


UEFI-Specific Information:
You should make sure your computer is booted in UEFI mode. Many motherboards will do so by default, but it can still vary from one platform to the next. Once booted into the install environment, you can double-check by looking for the /sys/firmware/efi/ directory. If it present, then you are presently running in UEFI mode; if not, then you are working in Legacy (BIOS) mode.

Boot your machine using the previously-created installation medium. You can choose to run the live image from the media, or, if you have the resources available, you can load the contents of the image into RAM. This option takes some time at the beginning but provides a quicker-overall installation procedure.

Once the live image has booted to a login prompt, log in as root using password voidlinux and then run:

# void-installer


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


Select your primary network interface. If you use DHCP on your network, select that option, otherwise the installer will prompt for IP Address, Netmask, and Gateway.

If you intend to use a wireless connection during the installation, you might have to configure it manually using wpa_supplicant and dhcpcd before running void-installer. Simply follow the instructions given here.


Choose whether you want to install from a local source (the packages that are included in the ISO) or from the network (in which case packages are downloaded from the Void remote repositories). Installing from the network allows you to install the most up-to-date packages available from the official repositories. Note that installing from local will also install any desktop included in the ISO (eg xfce)


Set a hostname for your computer remembering that hostnames should be all lower case, with no spaces.


Configure your default locale settings, this will be used to set the libc locale in a glibc environment.

The locale setting does not currently respond with the musl installer. Locales are not currently supported natively in musl.


Set your timezone based on standard timezone options.

Root Password

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

User Account

Choose a login (default void) and a descriptive name for that login (default Void User). Then enter and confirm the password for this default user. Finally you may choose to modify the group memberships for the user or go with the defaults.


Determine whether you'd like to use the installer to automatically install GRUB2 to the disk, or choose none if you'd like to install/configure a bootloader manually after completing the installation process.

UEFI-Specific Information:
Make sure to partition using the EFI System. Provided that you made sure to boot into UEFI mode, this should work on most well-behaved UEFI systems. See the notes section regarding possible issues.


Void does not provide an automatic/preset partition scheme, so you will need to create this manually using cfdisk. Please be sure to read the disclaimer regarding partition table formatting information if you are unfamiliar with the differences between BIOS/UEFI and MBR/GPT. Upon completion of your partitioning, choose 'Write' in cfdisk, type the word 'yes' to confirm, and select 'Quit' to return to the Void installer. See Disks for further information.

UEFI-Specific Information:

First, while UEFI systems are supposed to support MBR-based partition tables, the reality may be less predictable and the newer GPT scheme is going to be a better choice, especially if you have one of the larger Advanced Format disks. Use GPT.

Second, you need to create an EFI system partition, generally the first one. It does not need to be large; it is common to create one between 200MB and 1GB. When you create this partition in cfdisk, you need to change the type from the default "Linux" to the type appropriate to the ESP:

  • For GPT disks, change the type to EFI System.
  • For MBR (DOS) disks, create a primary partition and change the type to ef (EFI). [Not recommended]


Create the filesystems used to populate the partitions you just created. Choose your filesystem type, specify the mountpoint and create the filesystem, if necessary, for each partition you mean to modify. Once finished, select Back to return to the main installer menu. See Filesystems.

UEFI-Specific Information:
The EFI System Partition requires the use of the FAT12/16/32 filesystem. Be sure to select vfat for this filesystem and give it the mount point /boot/efi.

Once finished, select Back to return to the main installer menu. For additional information, see Disks#Filesystems.

Review Settings

Before installing, it is generally a good idea to review the installation settings. Arrow right from the main menu to select settings and use <enter> to review.


This step of the installer creates the filesystems specified in the previous step, then downloads all of the base packages (if configured to install via Network) and copies them to the target partition/partitions configured in the previous steps. After that, the installer generates an initramfs and installs GRUB2 to the bootable partition.

UEFI-Specific Information:
If you chose to install the Grub2 EFI loader, now is actually a good time (before you reboot) to double-check and see if the system firmware has Grub in its BootOrder. See the notes section below for details.

After the installation is successfully completed, you can reboot into your new Void Linux install!


Once you boot into your new Void installation, continue to Post-installation for further configuration tips.

Notes on Grub2 EFI Loader installation.

Grub2 possesses the ability to install an EFI loader to the EFI System Partition, as well as to modify the BootOrder variable in the system firmware. This works on most well-behaved UEFI imlementations. However, there are reports of a couple of issues on some systems/motherboards:

  • The BootOrder variable is not updated.
  • The BootOrder is not saved/followed by the system.

If the BootOrder variable fails to be updated, then the system will not boot the newly-installed Void system without some extra configuration.

To confirm that BootOrder has been updated before your final reboot, you can run the command efibootmgr with no arguments. The output should include something like this:

BootOrder: 0000,0003,0004
Boot0000* void_grub
Boot0003* CD/DVD Drive
Boot0004  EFI Internal Shell

See the man page for efibootmgr for more information on the capabilities and use of this program. If you see the option "void_grub" and it is listed first in BootOrder, then the variables have been successfully updated, and you can try to reboot. If not, keep reading.


In cases where BootOrder is either not updated, or not saved/followed after you reboot, then you should try copying grubx64.efi to the common default EFI loader location. You'll need to mount your EFI partition, and we'll assume it's on /mnt/. (In your installed Void system, the mount point would normally be /boot/efi/)

# install -D /mnt/EFI/void_grub/grubx64.efi /mnt/EFI/boot/bootx64.efi

On 32-bit firmware it should be

# install -D /mnt/EFI/void_grub/grubia32.efi /mnt/EFI/boot/bootia32.efi

You may then need to set the default boot disk in your computer's setup utility, but Void/Grub2 should boot correctly after this.

Note that you can boot your system back into the LiveCD to perform this operation if you were unable to boot to your Void Installation.

Cfdisk does not give me a choice of partition table type.

If the disk has already been initialized, cfdisk will continue with the partition table layout already present.

If your disk was previously partitioned with the MBR scheme, you will see the text "label: dos" near the top of the cfdisk screen. At this point, you will want to back out of the installer and run cfdisk manually with the "-z" option to start with an uninitialized disk layout, where you will then be prompted for the label type and continue with a new partition layout.

If the disk was previously using GPT, then you will see the text "Label: gpt" near the top of the cfdisk screen.

Multiple Partitions

It is common practice to put various subdirectories of / onto their own mounted partition, and there often good reasons for doing so.

However, it is important to note, because of Void's adoption of a more modern method for laying out the file system (known as the "/usr merge"), you must not try to place /usr on a separate partition. When you attempt to do so, the installer will inform you that this is not supported in Void. For information as to the "whats" and "whys" of the /usr merge, please see

Separate Boot Partition: While there are very few cases where this would be useful today, some people will opt to create a separate /boot partition, creating a nested mount scenario, where you have one partition mounted at /boot/ and a second partition mounted at /boot/efi.

This creates a problem in the installer where it may fail at grub-install, as the /boot/efi directory isn't created on the /boot/ partition. To avoid this particular failure the options are as follows:

  • In the Filesystems stage, make sure to assign the EFI System Partition last. As long as /boot is assigned before /boot/efi, then it will be mounted before the creation of the /boot/efi/ mountpoint, and no trouble will arise.
  • Don't use a separate /boot/ partition. One of the few cases where it might be desirable would be when having an encrypted root, but unencrypted /boot. Various ways of booting encrypted systems and the reasoning behind each is a rather large discussion of its own.
    • To the author's knowledge, Grub is the only EFI loader that, at the time of this writing, can open LUKS/LVM containers itself, so the use of other loaders would require the kernel and initrd to be on an unencrypted filesystem.
    • Another way to deal with this would be to use the ESP as /boot/ itself, but there are issues. Grub will need to be installed manually, as the installer assumes the ESP exists at /boot/efi/ and you will have to override this.
    • Lastly, you could use your preferred EFI loader to control all boot options, but allow it to chainload Grub which can handle booting your encrypted Linux installation. Obviously this does not avoid the use of Grub, so if that is one's goal, then this is not a satisfying option.

This can actually be an issue for any nested mount scenario, though such schemes aren't that common, and may not need to be configured at install-time.

Platform-specific notes

Bitness - Note that UEFI loader bitness (i.e. 32-bit or 64-bit) must match that of the firmware. So 64-bit firmware only runs a 64-bit loader (bootx64.efi), while 32-bit firmware only runs a 32-bit loader (bootia32.efi).

However, the loader can switch the CPU mode, so it is possible to boot a 64-bit kernel from a 32-bit EFI loader (given support in the loader), provided the CPU is actually x86_64 architecture. The reverse is also true (32-bit EFI kernel booted by a 64-bit EFI loader).

This applies only to firmware bitness. It is still not possible, for obvious reasons, to load a 64-bit OS on a 32-bit CPU.

Working Platforms

This procedure has been tested on the following systems: (Please add any systems/motherboards where this procedure has been successfully followed)

QEMU/KVM virtual machine on 64-bit OVMF firmware image (64-bit guest, 64-bit host) - x86_64 Void Install CD. BootOrder updated successfully, BootOrder obeyed by system.

QEMU/KVM virtual machine on 32-bit OVMF firmware image (32/64-bit guests, 64-bit host) - i686 and x86_64 Void Install CD. BootOrder updated successfully, BootOrder obeyed by system.

ASROCK Z77 Extreme4 (Intel Z77 chipset, 64-bit firmware) - x86_64 Void Install CD. BootOrder updated successfully, BootOrder obeyed by system.

Less-than-working Platforms

The following platforms have had issues with this procedure: (Please add any systems/motherboards that have issues related to EFI installation, as well as workarounds, if any.)

32-bit Firmware

Current ISOs have full support for loading both 32- and 64-bit OSes on both 32- and 64-bit firmwares. Tweaking the install script or adding packages to the install environment should no longer be necessary.

If GRUB cannot be found,_via_chroot#If_GRUB_cannot_be_found_.28a_note_about_UEFI.29

This article is issued from Voidlinux. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.