Try Omarchy in a VM first: UEFI, virtio, and the traps that break Hyprland

Want to see Omarchy without risking a laptop wipe? Start in a virtual machine. Official docs treat VMs as a first-class path — especially for unattended installs — and the same ISO you would flash to USB works on a virtual disk. This guide walks a safe first contact: firmware settings that matter, a Proxmox-style virtio/UEFI layout aligned with the official example, and the Hyprland traps that show up when the guest is underpowered or misconfigured.

This is a how-to for trying Omarchy. It is not a substitute for reading Getting Started before you touch bare metal.

What you are installing

Omarchy is an Arch-based, omakase desktop built around Hyprland and (as of 4.0 Quattro) a Quickshell desktop shell. You install from an ISO. The installer can do a full-disk install or a free-space install; in a disposable VM you almost always want full-disk on a virtual disk that you created for this purpose.

Verify ISO before you boot (from the v4.0.0 release):

• Download: https://iso.omarchy.org/omarchy-4.0.0.iso
• SHA256: 9224fab3720560f771969a99a499e5f7e0f8e2d6a0681d872d52f05fb5003da4

As of August 2026, the live ISO URL returns HTTP 200 for omarchy-4.0.0.iso (~6.27 GB / ~5.84 GiB) and the SHA256 matches the official release page. Always hash the file after downloading.

Always take a backup of important host data before any experiment that involves shared disks. A VM with its own dedicated virtual disk is the lowest-risk path.

Why VMs fail Omarchy (the short list)

Most first-boot pain is not "Omarchy is broken." It is firmware or input configuration:

1. Legacy BIOS / SeaBIOS — Omarchy expects UEFI. Use OVMF (or your hypervisor's UEFI firmware), not SeaBIOS.
2. Secure Boot / TPM left on — Official Getting Started requirement: you must turn Secure Boot and/or TPM off to install. On VMs that ship with Secure Boot keys pre-enrolled, disable that or use pre-enrolled-keys=0 on the EFI disk (see the official Proxmox snippet below).
3. Bluetooth keyboard at LUKS — Full-disk encryption will not accept a Bluetooth keyboard at the unlock prompt. Use a wired keyboard or a 2.4 GHz dongle on the host passed through as a normal HID device, or type into the VM console with your host keyboard.
4. Under-spec guest for a first look — Official docs do not publish a hard VM RAM minimum. If Hyprland feels sluggish, allocate at least 4–8 GB RAM and 4 vCPUs before troubleshooting config files.
5. Wrong disk selected — Full-disk install wipes the selected drive. In a VM, confirm you selected the virtual disk, not a passthrough physical disk.

Path A — Interactive install (best for first contact)

1. Create a UEFI guest

Minimum shape that matches official unattended/Proxmox guidance:

Note on generic QEMU/libvirt: Baeldung on UEFI in QEMU covers OVMF code/vars files and virt-manager's "Firmware: UEFI" option. For Proxmox, use OVMF + Q35 machine type.

2. Attach the Omarchy 4.0 ISO and boot

Boot the guest. You should land directly in the installer wizard.

3. Answer the wizard (and know the escape hatches)

From Getting Started:

• Answer keyboard, user, and confirmation screens as usual.
• Installing for someone else: Ctrl + C on the very first screen (keyboard selection) prepares the machine for another owner — personal setup is deferred until first boot.
• No encryption (special cases only): Ctrl + C on the disk formatting confirmation switches to an encryption-less install. Default remains encrypted; that is the responsible default.
• Select the virtual disk. Confirm. Installation finishes in under a minute on fast storage and typically within 5 minutes.

4. First boot

• Expect a LUKS passphrase prompt if you left encryption on. Host keyboard input via VGA/serial/SPICE console works.
• After unlock, you reach the Hyprland desktop. Stock Omarchy boots straight into Hyprland without a separate display-manager greeter.

5. After login — three binds to learn immediately

From the official migration and hotkey docs (Quattro menu model):

If the desktop feels empty, that is intentional: no dock, no desktop icons. Launch everything from the menu or hotkeys.

Path B — Unattended install (fleet / disposable labs)

Official path: attach a second drive labeled cidata carrying the configuration files the interactive installer would otherwise ask for. No custom ISO build is required.

Required on the cidata disk:

• user_configuration.json
• user_credentials.json or an empty file named defer-provisioning (prepare-for-another-owner mode)

Optional files documented upstream include git name/email, encryption flag, authorized_keys, and tailscale_authkey. Generate the password hash with:

openssl passwd -6 "yourpassword"

Build a tiny ISO (official example):

mkdir cidata
cp user_configuration.json user_credentials.json authorized_keys cidata/
genisoimage -output cidata.iso -volid cidata -joliet -rock cidata/

Official Proxmox example

From Unattended Installs:

qm create 101 --name my-omarchy \
  --bios ovmf --machine q35 --cpu host --cores 4 --memory 8192 \
  --ostype l26 --scsihw virtio-scsi-single \
  --efidisk0 local-lvm:0,efitype=4m,pre-enrolled-keys=0 \
  --scsi0 local-lvm:40,discard=on,iothread=1 \
  --net0 virtio,bridge=vmbr0 --vga virtio --serial0 socket \
  --ide2 local:iso/omarchy.iso,media=cdrom \
  --ide3 local:iso/cidata.iso,media=cdrom \
  --boot order='scsi0;ide2'

qm start 101

Key notes:

• Boot order lists the virtual disk first on purpose (falls back to CDROM when unformatted).
• If authorized_keys is present, the installer automatically enables sshd and opens the firewall port.
• Encrypted unattended still requires password entry at first boot: the disk_encryption block on the cidata drive carries the passphrase in plaintext, so treat the cidata ISO as a sensitive file.

Hyprland / Wayland traps in VMs

Display and 3D acceleration

• Prefer virtio display devices with 3D acceleration enabled where supported by the hypervisor.
• On VirtualBox or VMware, ensure EFI is selected and maximum video memory is assigned. KVM/QEMU and Proxmox provide the closest match to bare-metal Wayland behavior.

Scaling and "apps look huge"

Omarchy assumes a 2× high-resolution display via GDK_SCALE in its monitor defaults. On a standard 1080p 1× VM display window, oversized GTK apps are a common false alarm — adjust monitor scaling in ~/.config/hypr/monitors.lua rather than reinstalling.

macOS hosts (Apple Silicon / UTM)

When using UTM or Apple Virtualization framework on macOS, select UEFI boot and virtio-gpu. Keep in mind x86_64 emulation on ARM involves translation overhead.

When to move from VM to bare metal

Stay in the VM until you are comfortable with:

1. Unlocking LUKS and navigating workspaces (Super + 1..4).
2. Launching apps and managing system setup via Super + Space.
3. Running Update > Omarchy from the menu and testing a reboot cycle.

Then refer to Getting Started to prepare your bare-metal USB installer.