Windows — V\OS Docs

Running Vitruvian in a VM on Windows is the easiest way to look at it without touching a physical drive. This guide uses QEMU, the same emulator the project develops against on Linux; the commands below mirror the Linux guide closely.

What you need

Windows 10 or 11 (64-bit).
A reasonably modern processor. Hardware virtualization (Intel VT-x or AMD-V) makes a big difference; QEMU will work without it, just slower.
At least 8 GB of RAM on the host. The example commands give the guest 4 GB.
QEMU for Windows, installed from the official builds at qemu.weilnetz.de.

Install QEMU

Download the newest Windows installer from qemu.weilnetz.de/w64 and run it. The default install path is C:\Program Files\qemu. Write it down, you need it in the next step.

Add QEMU to PATH

QEMU needs to be reachable from any terminal window. To add it to your system PATH:

Press the Windows key, type env, and pick Edit the system environment variables.
Click Environment Variables….
Under System variables, select Path and click Edit….
Click New and paste the install path: C:\Program Files\qemu
Click OK on every open window to apply the change.

After this, open a new Command Prompt or PowerShell window; already-open windows keep the old PATH.

Verify the install

In a fresh terminal, run:

powershell

qemu-img.exe --version

You should get back a version line like qemu-img version 11.x, with a copyright notice from Fabrice Bellard and the QEMU project. If Windows complains the command isn’t recognized, the PATH step didn’t take. Redo it and open a new terminal.

Download an image

Grab the amd64 raw or ISO image from the download page. Keep it in an easy path, say C:\vitruvian\vitruvian.img.

Raw images are quicker to boot because there’s no installer step. Sections below cover both.

Boot a raw image

The command line differs from Linux in two ways: -accel whpx replaces -enable-kvm, and the -audiodev driver is dsound instead of PulseAudio. Everything else carries over.

Open an Administrator PowerShell (WHPX needs it) and run:

powershell

qemu-system-x86_64.exe `
  -accel whpx,kernel-irqchip=on `
  -drive file=C:\vitruvian\vitruvian.img,format=raw,if=virtio `
  -boot menu=on `
  -m 4G -cpu host -smp sockets=1,cores=2,threads=2 `
  -netdev user,id=mynet,hostfwd=tcp::2222-:22 `
  -device virtio-net-pci,netdev=mynet `
  -audiodev id=snd0,driver=dsound `
  -device ich9-intel-hda -device hda-output,audiodev=snd0

The backtick (`) is PowerShell’s line-continuation character; if you’d rather, paste it all on one line.

Boot an ISO

Same setup, but pointing at the ISO:

powershell

qemu-system-x86_64.exe `
  -accel whpx,kernel-irqchip=on `
  -drive file=C:\vitruvian\vitruvian.iso,format=raw,if=virtio `
  -boot menu=on `
  -m 4G -cpu host -smp sockets=1,cores=2,threads=2 `
  -netdev user,id=mynet,hostfwd=tcp::2222-:22 `
  -device virtio-net-pci,netdev=mynet `
  -audiodev id=snd0,driver=dsound `
  -device ich9-intel-hda -device hda-output,audiodev=snd0

SSH into the guest

The hostfwd=tcp::2222-:22 line forwards the guest’s SSH port to localhost:2222 on your Windows machine. From your normal terminal:

powershell

ssh -p 2222 vitruvian@127.0.0.1

Troubleshooting

“No accelerator found”: WHPX isn’t available. Make sure virtualization is enabled in the BIOS (Intel VT-x / AMD-V) and that Hyper-V isn’t holding the hardware in an incompatible state. As a fallback, drop -accel whpx,kernel-irqchip=on and accept slower emulation.
The window opens and closes instantly: check the terminal output for the real error, usually a typo in a path or a flag. With -boot menu=on you should at minimum reach the boot menu.
No sound / no network: those need the -audiodev and -netdev flags present on the command line; they’re easy to drop accidentally.

Most issues at this stage are small command-line slips. The error message in the terminal names the culprit.

V\OS Docs