Testing and Booting

You have an ISO, from a GitHub Actions run or your own build. This page covers checking it, trying it in a virtual machine, writing it to a USB stick and booting a real PC.

1. Check the download

An ISO from GitHub comes in a zip with a .sha256 file next to it. Unzip both into one folder, open a terminal there and compare the checksum:

System	Command	Good result
Windows (PowerShell)	Get-FileHash .\mydistro.iso -Algorithm SHA256	The Hash matches the long number in mydistro.iso.sha256 (open it in Notepad). Upper or lower case doesn't matter.
macOS	shasum -a 256 -c mydistro.iso.sha256	mydistro.iso: OK
Linux	sha256sum -c mydistro.iso.sha256	mydistro.iso: OK

If the checksum doesn't match, download it again. A broken download is the most common reason an ISO won't boot.

To look inside the ISO on any system, run python -m linuxlive inspect-iso from a linuxlive checkout (see Building Locally: Look inside the ISO):

python -m linuxlive inspect-iso --no-checksum path/to/mydistro.iso

2. Try it in VirtualBox

VirtualBox runs on Windows, Linux and Intel Macs. The steps are for VirtualBox 7.

1. Click New. Give the machine a name, and for ISO Image choose your ISO.
2. If VirtualBox offers an unattended installation, turn it off by ticking Skip Unattended Installation. There is nothing to install: the ISO is a live system.
3. Set Type to Linux and Version to Ubuntu (64-bit) or Fedora (64-bit), to match the base.
4. Hardware: 4096 MB of memory and 2 CPUs. Tick Enable EFI to test a UEFI boot, or leave it off for a BIOS boot. Both work.
5. Hard disk: choose Do Not Add a Virtual Hard Disk. A live system doesn't need one. Confirm the warning.
6. Finish. Then, under Settings → Display, check that the graphics controller is VMSVGA, and give it 128 MB of video memory.
7. Click Start.

You will see:

• a boot menu with Try My Distro 0.1, Try My Distro 0.1 (safe graphics) and, under UEFI, UEFI firmware settings. The first entry starts by itself after 5 seconds;
• a boot splash with your logo. In VirtualBox it's often a text screen with your distro's name instead, because early graphics aren't available there. That's normal;
• your desktop with your wallpaper, logged in automatically. On Ubuntu the user is live, on Fedora liveuser, with no password.

If the screen is small, change the resolution in the desktop's display settings. VirtualBox Guest Additions aren't included, so the window doesn't resize the desktop automatically.

3. Try it in QEMU (Linux)

The automated boot test

scripts/boottest.py is what CI uses. It boots the ISO without a window, watches what the system reports on its serial console, and writes result.json, logs and, with --session, screenshots. It needs qemu-system-x86 and ovmf (see Building Locally), and works only with ISOs built by linuxlive.

One boot, from USB under UEFI, waiting for the desktop:

python scripts/boottest.py --iso build/lawndarts.iso --mode uefi-usb --session --out build/results/modes/uefi-usb

All five modes, then the same checks CI runs:

python scripts/boottest.py --iso build/lawndarts.iso --mode uefi-usb --session --out build/results/modes/uefi-usb
for mode in uefi-sb-cd uefi-cd bios-cd bios-usb; do
  python scripts/boottest.py --iso build/lawndarts.iso --mode "$mode" --out "build/results/modes/$mode"
done
python -m linuxlive inspect-iso build/lawndarts.iso --json build/results/iso.json
printf '{"base": "ubuntu"}\n' > build/results/meta.json
python -m linuxlive verify-results --spec examples/lawndarts-ubuntu.yaml --results build/results

Set "base" in meta.json to your spec's base. If you only ran the uefi-usb boot, add --check iso,session to the last command.

The modes are uefi-usb, uefi-sb-cd (Secure Boot on), uefi-cd, bios-cd and bios-usb. Other useful options: --memory (MiB, default 4096), --cpus (default 2), and --accel tcg to run without KVM, which is very slow. Timeouts grow automatically without KVM.

Looking at it yourself

To click around in a window instead:

qemu-system-x86_64 -enable-kvm -m 4096 -smp 2 -cdrom build/lawndarts.iso

That boots with BIOS. For UEFI, give QEMU the OVMF firmware and its own copy of the firmware's settings store:

cp /usr/share/OVMF/OVMF_VARS_4M.fd build/vars.fd
qemu-system-x86_64 -enable-kvm -machine q35 -m 4096 -smp 2 \n  -drive if=pflash,format=raw,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \n  -drive if=pflash,format=raw,file=build/vars.fd \n  -cdrom build/lawndarts.iso

Those are the paths on Ubuntu 24.04; other distributions keep OVMF elsewhere, often in /usr/share/edk2/ovmf/.

4. Write a USB stick

You need a stick of 8 GB or more. Everything on it will be erased. Fedora ISOs are 4 to 4.5 GiB, Ubuntu ones under 3 GiB.

System	Tool	How
Windows	Rufus	Pick the stick and the ISO, then Start. When Rufus says it found an ISOHybrid image, choose Write in DD Image mode.
Windows, macOS, Linux	Fedora Media Writer	Choose Select .iso file, pick the ISO and the stick, then Write.
Windows, macOS, Linux	balenaEtcher	Flash from file, pick the stick, Flash.
Linux	GNOME Disks	Select the stick, open the menu (⋮), Restore Disk Image, pick the ISO.
Linux	dd	sudo dd if=mydistro.iso of=/dev/sdX bs=4M status=progress oflag=sync. Replace sdX with the stick, found with lsblk. Picking the wrong disk erases it.

These all copy the image to the stick byte for byte, which is what linuxlive's USB boot tests do. Tools that unpack the ISO onto the stick instead (Rufus's "ISO Image mode", Ventoy, UNetbootin) haven't been tried.

5. Boot a PC from the stick

1. Plug the stick in and restart the computer.
2. As soon as it powers on, press the boot menu key for your brand, and pick the USB stick. If it's listed twice, pick the entry with UEFI in its name.
3. The linuxlive boot menu appears. Press Enter, or wait 5 seconds.

Brand	Boot menu key	Notes
Dell	F12	F2 opens the firmware setup.
HP	Esc, then F9	On many models F9 alone works.
Lenovo	F12 (sometimes Fn+F12)	IdeaPad and Yoga: press the small Novo button with the laptop off, then choose Boot Menu.
Acer	F12	If nothing happens, enable "F12 Boot Menu" in the firmware setup (F2) first.
ASUS	Esc (laptops), F8 (desktop boards)	F2 or Del opens the firmware setup.
MSI	F11
Gigabyte	F12
Microsoft Surface	Hold volume-down, press power	Keep holding volume-down until the Surface logo goes away.
Mac with Intel	Hold Option	Pick EFI Boot. Macs with a T2 chip need "Allow booting from external media" turned on first.
Mac with Apple silicon	—	Not supported: the ISOs are for Intel and AMD processors.
Anything else	Try F12, F11, Esc, F10, F9 or F8	Many computers show the key on screen for a moment.

Secure Boot

You can leave Secure Boot on. The ISOs boot through the signed boot chain (shim, GRUB and kernel) of Ubuntu or Fedora, which PCs trust by default. This has been tested with Secure Boot firmware in QEMU, not yet on real PCs. If a PC refuses to boot the stick, say so in an issue. Turning Secure Boot off in the firmware setup is a workaround.

The boot menu

Entry	When to use it
Try	Normally.
Try (safe graphics)	The screen stays black, or is garbled, after the splash. It starts without the graphics driver's high-resolution mode (nomodeset).
UEFI firmware settings	Opens the PC's firmware setup (UEFI only).

In the live session

• You're logged in automatically, as live on Ubuntu or liveuser on Fedora, with no password.
• Nothing is saved. Everything happens in memory and is gone when you shut down. Save files to another USB drive or online.
• Wi-Fi and wired networks are managed from the network icon in the panel.
• More apps can be installed from the software store (Flathub), until shutdown.
• Hardware support is what Ubuntu 26.04's or Fedora 44's kernel provides. NVIDIA's proprietary driver isn't included; NVIDIA cards use the open nouveau driver.
• To install the system to a disk: there's no installer yet. See Known Limitations.

Reporting a problem

Open an issue and include:

• your spec, and how you built it (a link to the Actions run, or "locally");
• where you booted it: VirtualBox (version and settings) or the PC's make and model;
• BIOS or UEFI, and Secure Boot on or off;
• which boot menu entry you chose, and what you saw. A phone photo of the screen helps.