Write the stick#

The image is a hybrid ISO. Writing it to a USB stick byte for byte is the supported way, and the same file boots from a virtual CD drive on a hypervisor without being written to anything. Nothing here needs a special tool beyond dd on Unix or a DD-mode writer on Windows: an ISO written through a "make bootable USB" wizard that repacks the filesystem will usually fail to boot, and it will fail in a way that looks like a hardware problem.

Linux#

lsblk -d -o NAME,SIZE,MODEL
sudo dd if=wheelhouse-0.5.1-amd64.iso of=/dev/sdX bs=4M status=progress conv=fsync

Write to the whole device (/dev/sdb), not to a partition on it (/dev/sdb1). conv=fsync matters: without it dd returns as soon as the kernel has accepted the data, and pulling the stick out at that point leaves you with a partial image and a boot that stops halfway through GRUB.

macOS#

diskutil list
diskutil unmountDisk /dev/diskN
sudo dd if=wheelhouse-0.5.1-amd64.iso of=/dev/rdiskN bs=4m

Unmount the disk; do not eject it. Write to the raw device /dev/rdiskN rather than /dev/diskN — the buffered device works and takes several times as long.

Windows#

Use Rufus or balenaEtcher. In Rufus, choose DD image mode rather than ISO mode when it offers the choice. ISO mode repacks the files onto a new filesystem, which loses the hybrid boot layout.

Check what landed on the stick#

Worth doing on a stick you have written before, or one that has lived in a pocket. Read back exactly as many bytes as the image has and hash them:

size=$(stat -c %s wheelhouse-0.5.1-amd64.iso)
sudo dd if=/dev/sdX bs=4M count=$((size / 4194304 + 1)) iflag=count_bytes,fullblock \
  | head -c "$size" | sha256sum
sha256sum wheelhouse-0.5.1-amd64.iso

The two hashes must match. They will not match if you compare the whole device, because the stick is larger than the image and the trailing bytes are whatever was there before.

Booting a VM instead#

There is no qcow2, raw, OVA or VHD image; the build emits an ISO and nothing else. On a hypervisor, attach the ISO you downloaded as a virtual CD drive and skip this page entirely — Installing in a VM has the rest.

See also#

• Boot it — the next step.
• Download and verify — check the ISO before you write it.
• Installing in a VM — no stick required.
• Installing without a keyboard — the second stick, the one that holds the answers.
• The image flavor — what is inside the file you are writing.

Checked against docs/install.md, docs/hardware.md, packaging/iso/build-iso.sh.