# Omarchy on WSL2: Hyprland will not run, and what to do instead
Omarchy on WSL2: Hyprland cannot start because WSL2 exposes no DRM node. What community .wsl images actually give you, and how to get the real desktop.
> **Short answer:** You cannot run the Omarchy desktop on WSL2. Hyprland needs a DRM node for its GBM allocator and WSL2 exposes only /dev/dxg, so the compositor refuses to start, nested or headless. Community .wsl images give you Omarchy's CLI, themes and tooling only. For the real desktop on Windows, use Try Omarchy for Windows or a Hyper-V VM.
- Applies to Omarchy: 3.x and later
- Status: partial
- Last verified: 2026-09-16
- Canonical: https://omarchylinux.org/run/wsl2/
_Unofficial community page. Not affiliated with 37signals or the Omacom Foundation. Omarchy is a registered trademark of 37signals LLC._

Short version: WSL2 can run Omarchy's command line, and it cannot run Omarchy's desktop. That split is not a packaging problem someone will fix next month. It comes from what WSL2 exposes to Linux. It was already the answer when the first WSL thread appeared in August 2025, back on Omarchy 1.x, and it is still the answer on 4.0.4.

## What runs and what does not

| Piece | On WSL2 |
|---|---|
| Omarchy CLI, `omarchy-*` scripts, themes, Neovim, lazygit, btop, starship | Works |
| Individual GUI apps as normal Windows windows, through WSLg | Works |
| Hyprland, the Quickshell bar, lock screen, screensavers, the whole Omarchy 4 desktop | Does not start |
| Limine, snapper rollback, LUKS, Plymouth, hardware drivers | Not applicable, no boot sequence and no block device |

Omarchy's own manual has an "[Omarchy on...](https://omarchy.org/manual/omarchy-on/)" chapter listing Asahi, Parallels, VirtualBox, VMware Workstation, the Steam Deck and a NixOS port. WSL is not on it, and the string "wsl" does not appear anywhere in the v4.0.4 tree.

## Why Hyprland cannot start on WSL2

Linux inside WSL2 never sees a DRM device. What it sees instead is `/dev/dxg`, a paravirtualised Direct3D 12 device that Mesa's d3d12 driver talks to through dxcore. There is no `/dev/dri/card0` and no render node. You can confirm that from inside any WSL2 distro:

```bash
ls -l /dev/dri /dev/dxg
```

Since v0.42.0 in August 2024, Hyprland's backends live in a separate library, Aquamarine, and Aquamarine only knows how to build a GBM buffer allocator, which needs a DRM file descriptor. When none of its backends can hand one over, `src/backend/Backend.cpp` logs `Cannot open backend: no allocator available` and gives up. That code is still in hyprwm/aquamarine as of this page's verification date. The headless backend is no escape hatch: its `drmFD()` returns `-1`, so it hits the same wall.

Running Hyprland nested inside WSLg fails for a different reason. In the protocol trace clarenceb captured for [clarenceb/omarchy-wsl2](https://github.com/clarenceb/omarchy-wsl2), WSLg's Weston fork offered `wl_shm` but not `zwp_linux_dmabuf_v1`, and Aquamarine's Wayland backend treats dmabuf as required. That trace came from one ARM64 machine, so re-run it on your own build before assuming it still holds. Upstream has not been coy about any of this. When someone asked in October 2023 whether Hyprland could run in WSL, in [Hyprland issue #3479](https://github.com/hyprwm/Hyprland/issues/3479), the maintainer closed it the same day with a one word answer: "no". The crash log in that report is from the older wlroots backend, but the missing DRM fd is the same complaint. The issue has stayed closed.

wlroots compositors such as sway do start under WSL2, because wlroots will settle for plain shared memory buffers and a CPU renderer when there is no DRM node to build GBM on. That gets you a tiling desktop, but it is a different compositor with its own config, not Omarchy.

## If you want the real Omarchy desktop on Windows

Use a virtual machine, not WSL2.

1. **Try Omarchy for Windows.** [omacom/try-omarchy-windows](https://github.com/omacom/try-omarchy-windows) runs a prebuilt Omarchy image under QEMU on the Windows Hypervisor Platform, the same hypervisor layer WSL2 depends on, so the Hyper-V role is not required and Windows Home works. The current release is v0.0.19-preview, published 2026-09-16, carrying Omarchy 4.0.3. It lives in the same GitHub organisation as Omarchy itself, but it is preview software with an open v1 checklist, so treat it as a trial rather than a daily driver.
2. **Hyper-V.** Available on Windows Pro, Education and Enterprise. There is a community guide at [discussion #445](https://github.com/omacom/omarchy/discussions/445), but read it with the date in mind: it was written in August 2025 against a plain Arch ISO with GRUB, and Omarchy now ships its own installer ISO with Limine. See [Omarchy on Hyper-V](/run/hyper-v/) for the current steps.
3. **VirtualBox or VMware.** Both are covered in the manual and on this site at [VirtualBox](/run/virtualbox/) and [VMware](/run/vmware-workstation-fusion/). Expect the usual VM compromises, listed at [what breaks in a VM](/run/what-breaks-in-a-vm/).

Download the ISO from [omarchy.org](https://omarchy.org) and check it against the [verification steps](/verify/) before you boot it.

## If you only want the Omarchy CLI on WSL2

Three community builders exist. All of them produce a `.wsl` file you install with `wsl --install --from-file`. None of them gives you Hyprland, and all of them are young, so read the repo before you trust it.

- [craigloewen-msft/Omarchy-wsl](https://github.com/craigloewen-msft/Omarchy-wsl) builds a CLI and TUI image with `wslc`, on x86_64 and ARM64. It pins the Omarchy checkout to v4.0.0 by default and says so. Its README calls it a community project.
- [taufderl/omarchy-wsl](https://github.com/taufderl/omarchy-wsl) installs the actual `omarchy` pacman package with pacstrap, so the full dependency graph comes along, then lets Omarchy's own scripts under `/usr/share/omarchy/install/` do the setup, then documents every piece that does not apply under WSL2. Its stated status is that it runs without a Hyprland desktop session.
- [clarenceb/omarchy-wsl2](https://github.com/clarenceb/omarchy-wsl2) ships Omarchy's tooling plus a sway session configured with Omarchy keybindings, gaps and themes, rendered on the CPU with pixman. No animations, no blur, no rounded corners, no Xwayland, one output.

If you would rather do it by hand, the walkthrough by nunix in [discussion #473](https://github.com/omacom/omarchy/discussions/473) is the original recipe: install the `archlinux` WSL distro, create a user, add them to sudoers, set `[user] default` in `/etc/wsl.conf`, then run Omarchy's installer with the network, power, login, nvidia, firewall, bluetooth and asdcontrol steps commented out. That was written in August 2025 against Omarchy 1.x, when the installer was a single `install.sh` sourcing scripts under `config/`, `development/` and `desktop/`. The 4.0.4 tree has `install/config/`, `install/hardware/`, `install/login/`, `install/post-install/` and `install/user/` instead, and there is no `power.sh` or `asdcontrol.sh` any more, so the exact file list no longer matches. Use it as a map, not a script.

## Is an official image coming

There is no published `.wsl` artifact. The URL pattern proposed in the request, next to the ISO on iso.omarchy.org, returns 404 for both 4.0.2 and 4.0.4 as of 2026-09-16.

Two threads are open. [omarchy-iso issue #150](https://github.com/omacom/omarchy-iso/issues/150), filed 2026-09-03 by linghengqian, asks the project to build and publish a `.wsl` artifact the way Ubuntu does alongside its ISOs. [Discussion #10748](https://github.com/omacom/omarchy/discussions/10748), opened 2026-09-08, asks the same thing in one line and has no replies. Neither has a maintainer answer. Nothing in the 4.0.4 tree suggests WSL support is being built.

Be clear about what an official image would and would not change. It would make the CLI install one command. It would not make Hyprland start, because that limitation is in WSL2's device model, not in Omarchy's packaging.

## What to watch for on newer versions

The thing that would actually change this answer is Microsoft exposing a DRM render node inside WSL2, WSLg starting to advertise dmabuf, or Aquamarine gaining a non GBM allocator path. Watch the hyprwm/aquamarine and microsoft/wslg repos rather than the Omarchy tracker; [Hyprland issue #3479](https://github.com/hyprwm/Hyprland/issues/3479) has been closed since 2023 and will not be where news lands.

On the Omarchy side, the 3.x to 4.x move matters for any WSL guide you find. Config now lives in Lua files with an `o.bind("SUPER + K", "Label", action)` DSL instead of `~/.config/hypr/*.conf`, and the bar, menus, notifications and lock screen run inside one long running Quickshell process. Any WSL walkthrough written before 2026-08-14 predates that. See [the 3 to 4 upgrade](/upgrade/3-to-4-quattro/) and the [hyprland.conf to Lua migration](/reference/hyprland-conf-to-lua-migration/) for what changed.

Evidence for the CLI builders is thin. Two of the three repos had zero or one star and no pushes since late August 2026 when this page was checked. Nobody has published a long running report of Omarchy under WSL2 on a daily workload, so treat these as experiments.

## Sources

- [Hyprland issue #3479: May I ask if there is a way to run Hyprland in wsl](https://github.com/hyprwm/Hyprland/issues/3479)
- [Discussion #473: wsl?](https://github.com/omacom/omarchy/discussions/473)
- [Discussion #10748: push a wsl image.?](https://github.com/omacom/omarchy/discussions/10748)
- [omarchy-iso issue #150: Build and publish omarchy's .wsl artifact](https://github.com/omacom/omarchy-iso/issues/150)
- [Discussion #445: Guide - Omarchy on Hyper-V](https://github.com/omacom/omarchy/discussions/445)
- [omacom/try-omarchy-windows: Use Omarchy Linux on Windows without any hassle](https://github.com/omacom/try-omarchy-windows)
- [craigloewen-msft/Omarchy-wsl: build a .wsl package for the CLI flavour of Omarchy](https://github.com/craigloewen-msft/Omarchy-wsl)
- [clarenceb/omarchy-wsl2: Omarchy tooling as a WSL2 distro, with sway instead of Hyprland](https://github.com/clarenceb/omarchy-wsl2)
- [taufderl/omarchy-wsl: Run Omarchy on Windows](https://github.com/taufderl/omarchy-wsl)
- [Omarchy manual: Omarchy on...](https://omarchy.org/manual/omarchy-on/)
- [Release v4.0.4](https://github.com/omacom/omarchy/releases/tag/v4.0.4)