> For the complete documentation index, see [llms.txt](https://docs.monarchlinux.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.monarchlinux.com/getting-started/virtual-machines.md).

# Virtual Machines

Run Monarch in a virtual machine and troubleshoot display scaling with Niri.

QEMU is the officially supported way to test Monarch in a virtual machine. VirtualBox and VMware Workstation may work, but their virtual graphics devices and Wayland support vary and are not tested as part of the Monarch release process.

For a comfortable test machine, start with:

* 8 GiB of RAM
* 4 virtual CPUs
* A 40 GiB or larger virtual disk
* Hardware virtualization enabled on the host

Boot the ISO and follow the [installation guide](https://docs.monarchlinux.com/getting-started/installation). A full-disk installation is appropriate for an empty virtual disk.

## Display scaling

Monarch uses Niri, not Hyprland. Do not edit `~/.config/hypr/monitors.conf` or follow Hyprland monitor instructions from older releases.

To configure the virtual display:

1. Press **`SUPER + ALT + Space`**.
2. Open **Actions → Hardware → Displays**.
3. Adjust the scale or open the display arrangement tool.

You can also cycle the focused display through Monarch's standard scales with **`SUPER + CTRL + D`**.

From a terminal, list Niri's displays and set a persistent scale:

```bash
monarch display list
monarch display scale <output> 1
```

Replace `<output>` with a name reported by `monarch display list`.

## VirtualBox and VMware

These hypervisors are best-effort only. If the desktop does not resize with the VM window:

1. Install and enable the guest tools provided by the hypervisor.
2. Reboot the guest.
3. Use Monarch's **Displays** panel or `monarch display scale` to correct the scale.

If the compositor fails to start, try another virtual graphics controller or use QEMU before reporting a Monarch installer issue.

{% hint style="warning" %}
Instructions written for Omarchy's Hyprland configuration do not apply to current Monarch installations.
{% endhint %}
