Testing the Void Installer ISO on Real Hardware

End-to-end guide to take the freshly built out/void-install.iso, write it to a USB stick, and run the installer on a real machine (e.g. the XPS 17 9700).

⚠️ DESTRUCTIVE. The installer will reformat the partition you select. Make a Timeshift / dd backup of any disk you care about before booting from the stick. The installer never touches the EFI System Partition — your existing Windows bootloader stays put.

1 · Prerequisites

Item	Detail
USB stick	≥ 2 GiB, all data on it will be lost
Target machine	UEFI firmware, x86_64, ≥ 4 GiB RAM, ≥ 30 GiB free on the target partition
Host (this laptop)	Linux with `lsblk`, `dd`, `sync`, root access
Built ISO	`out/void-install.iso` (run `make iso` first if missing)
Network	Ethernet or known-good Wi-Fi credentials (NetworkManager nmtui works in the live env)

2 · Build the production ISO

cd ~/Sources/void-installer
make iso          # builds out/void-install.iso (~1.3 GiB)
sha256sum out/void-install.iso

The build runs entirely inside Docker, so the host stays clean. Output: out/void-install.iso. Keep the sha256 — you'll verify it after dd.

3 · Identify the USB device

Plug the USB stick in. Then:

lsblk -o NAME,SIZE,MODEL,TRAN,MOUNTPOINTS

Find the line with usb in the TRAN column. Typical names: /dev/sdb, /dev/sdc. Never pick /dev/sda (your system disk) or anything starting with nvme0n1 (your NVMe). Confirm with the size (matches your stick).

Set a shell variable so you can't typo it later:

USB=/dev/sdX     # ← replace X with the actual letter you saw above
echo "WILL ERASE: $USB"
lsblk "$USB"     # double-check

If the stick has any mounted partitions, unmount them all:

for p in $(lsblk -nro NAME "$USB" | tail -n +2); do
    sudo umount "/dev/$p" 2>/dev/null || true
done

4 · Flash the ISO

The Void ISO is a hybrid ISO (xorriso-isohybrid), so plain dd works for both UEFI and legacy BIOS. No partitioning, no formatting, no GUI tool needed.

sudo dd if=out/void-install.iso of="$USB" bs=4M status=progress conv=fsync oflag=direct
sync

When it finishes (~1-3 min on USB 3.x), verify the write actually landed:

sudo dd if="$USB" bs=4M count=$(( $(stat -c%s out/void-install.iso) / 4 / 1024 / 1024 )) \
    status=none | sha256sum
sha256sum out/void-install.iso

The two hashes should match (truncated read length matters; if they differ try adding iflag=fullblock).

Alternative GUI tools that also work: GNOME Disks → "Restore Disk Image…", balenaEtcher, Ventoy. Avoid Rufus' "ISO mode" → it rebuilds the partition table and can break UEFI boot.

Eject the stick cleanly:

sudo eject "$USB"

5 · Boot the target machine from USB

Plug the stick into the target laptop (not the host).
Power on while spamming the firmware boot-menu key:
- Dell XPS 17: F12
- ThinkPad: F12
- HP: F9
- Most others: F8, F10, F11, Esc
From the one-shot boot menu, select the entry that contains your USB stick's model name and the prefix UEFI: (NOT the legacy/MBR entry).
The Void Linux GRUB menu appears — keep the default "Void Linux installer" entry (or wait for the timeout).
After ~10-30 s you land on a console as root and the installer banner appears.

Secure Boot: The ISO is not signed for Secure Boot. Disable Secure Boot in the firmware setup before the first boot, or shim signing will fail. You can re-enable it after the install completes (Void's GRUB will not validate, so leave it off unless you sign the kernel yourself).

6 · Run the installer

When you see the banner, follow the on-screen prompts. The installer is unattended-by-default for the developer profile and will:

Bring up networking (DHCP on Ethernet, or nmtui for Wi-Fi if no link).
Show the disk picker — select your target btrfs partition (e.g. /dev/nvme0n1p5). The picker refuses to format the EFI partition or anything labelled NTFS / Windows.
Confirm the summary by typing YES (case-sensitive). Last chance to abort.
Wipe the chosen partition, mkfs.btrfs, mount subvolumes.
Bootstrap base-system + ~140 packages from the public Void mirror.
Configure users, sudo, services, GRUB chained next to the existing Windows loader.
Reboot. Remove the USB stick before GRUB starts.

Total install time on a Gen-12 laptop with NVMe + 1 Gbps internet: 8-15 min.

7 · First-boot checks

After the system reboots, log in as moze (password from your secrets.env).

Check	Command	Expected
Cinnamon session	(lightdm shows it on login)	green Cinnamon wallpaper
Network	`nmcli c`	active connection
Audio	open `pavucontrol`	sink listed, no errors
Bluetooth	tray icon → "Devices…"	scan starts
Printer	Settings → Printers	CUPS server reachable
Trackpad gestures	three-finger swipe up	virtual-desktop overview
Screenshot	press PrintScreen	flameshot UI appears
Snapshots	`sudo timeshift --list`	(empty list, no errors)
Pre-upgrade snapshot	`sudo xbps-install -Sun \| tail`	wrapper prints `[snapshot]` line
GPU PRIME offload	`nvidia-smi`	NVIDIA GPU detected
Docker	`docker run --rm hello-world`	"Hello from Docker!"
VS Code	`code --version`	version printed

8 · Recovery (if something goes wrong)

The installer never overwrites your EFI partition and never touches partitions other than the one you selected. To roll back:

Boot Windows again: in firmware setup, move the Windows boot entry above Void in the EFI boot order. Or hit the one-shot boot menu and pick Windows.
Wipe the Void partition: boot back into the live USB, mount your old filesystem (e.g. mount /dev/nvme0n1p5 /mnt), and either restore from your backup or mkfs.<oldfs> /dev/nvme0n1p5.
Restore the GRUB menu only: in the live USB, mount /dev/<EFI> /mnt/efi && grub-install --efi-directory=/mnt/efi --bootloader-id=Windows --removable (after chrooting into your old install) or use Microsoft's "Startup Repair" from a Windows install media.
Restore a Timeshift snapshot (post-install): boot into the live USB, xbps-install -Sy timeshift, then timeshift --restore --snapshot <name>.

9 · Reporting bugs

If the installer aborts:

The serial / TUI shows the failing line and a log path.
Copy /tmp/installer.log and /var/log/void-installer.log off the live USB (e.g. via scp over Ethernet) and attach them to the bug report.
Note: which step failed, exact partition layout (lsblk -f), firmware mode (UEFI vs BIOS), and whether Secure Boot was on.

6.8 KiB Raw Blame History