Installing Omarchy 4 in VMware Workstation on Debian: From Black Screen to Beautiful Desktop

I wanted to explore Omarchy without replacing Debian or immediately committing an external SSD to it. Since VMware Workstation was already part of my home lab, installing Omarchy in a virtual machine seemed like the safest way to see what this opinionated Arch Linux and Hyprland environment was all about.

The installation worked, but getting the graphical desktop to appear required considerably more troubleshooting than I expected. What began as a black screen and an enormous mouse pointer eventually became a fully functioning Omarchy 4 desktop.

This is the complete story of how I set it up and what finally fixed it.

What Is Omarchy?

Omarchy is an opinionated Linux distribution based on Arch Linux and the Hyprland tiling Wayland compositor. It is designed primarily for developers and includes an attractive, keyboard-driven environment with terminal tools, editors, development runtimes, themes, and productivity applications.

Unlike Debian with Cinnamon, Omarchy is not intended to provide a conventional point-and-click desktop. Keyboard shortcuts, tiled windows, terminal commands, and configuration files are fundamental parts of the experience.

That difference was one of the main reasons I wanted to try it.

Preparing the Omarchy ISO

I downloaded the Omarchy 4.0.0 ISO:

omarchy-4.0.0.iso

Before using it, I verified the download with:

sha256sum ~/Downloads/Omarchy/omarchy-4.0.0.iso

The result was:

9224fab3720560f771969a99a499e5f7e0f8e2d6a0681d872d52f05fb5003da4

This matched the checksum published for the official Omarchy 4.0.0 release.

I initially wrote the ISO to a 128 GB USB flash drive after confirming that the flash drive was /dev/sdg and that my 2 TB Debian system disk was /dev/sda.

The command used was:

sudo dd if="$HOME/Downloads/Omarchy/omarchy-4.0.0.iso" of=/dev/sdg bs=4M status=progress conv=fsync

The USB became a proper Omarchy installer. However, because Omarchy’s installer is not a traditional live desktop, the flash drive alone would not provide the complete persistent experience I wanted. A separate external SSD would still be required for a safe physical installation.

While considering that option, I decided to try Omarchy in VMware Workstation first.

Creating the Omarchy Virtual Machine

I configured the Omarchy VM with the following resources:

Guest operating system: Linux, Other Linux 6.x kernel 64-bit
Memory: 8 GB
Number of processors: 1
Cores per processor: 4
Total processor cores: 4
Virtual disk: 100 GB
Network: NAT
Firmware: UEFI
CD/DVD: Omarchy 4.0.0 ISO
Graphics memory: 256 MB

Under VMware’s processor settings, I left all the additional virtualization-engine options unchecked:

Virtualize Intel VT-x/EPT or AMD-V/RVI: Off
Virtualize CPU performance counters: Off
Virtualize IOMMU: Off

These options expose virtualization features inside the guest for nested virtual machines. Omarchy itself does not require them.

Under Display settings, I enabled:

Accelerate 3D graphics

VMware warned that 3D acceleration was not supported by the selected guest operating system. Nevertheless, Omarchy’s Hyprland desktop needed the option enabled to progress beyond the initial graphical problems. The final solution would combine VMware’s 3D setting with software OpenGL inside Omarchy.

The Black-Screen Problem

Omarchy installed and booted, but instead of a usable desktop, VMware displayed a black screen with an enormous pointer.

At one point, I used Ctrl+Alt+F3 while attempting to reach a terminal. The keyboard combination went to my Debian host instead of the VM and switched Debian to a text console. Pressing Ctrl+Alt+F7 restored the Debian graphical session.

This taught me an important lesson: when using function-key console shortcuts in VMware, the VM must have complete keyboard focus. Otherwise, the host operating system may receive the shortcut.

Fortunately, I discovered a much easier method. Inside the black Omarchy display, the following shortcut opened a working terminal:

Super + Enter

The Super key is the Windows key on a conventional PC keyboard.

This gave me a usable Omarchy terminal without switching virtual consoles.

Confirming the Omarchy Installation

From the terminal, I verified the user and operating system:

whoami
cat /etc/os-release | head

The output confirmed that I was logged in as my normal user and running:

NAME="Omarchy"
BUILD_ID="4.0.0"
VERSION_ID="4.0.0"
ID_LIKE=arch

Installing VMware Tools

The next requirement was open-vm-tools, which integrates Linux guests with VMware.

A safe Arch Linux installation command is:

sudo pacman -Syu open-vm-tools

I then enabled and started the VMware service:

sudo systemctl enable --now vmtoolsd

I verified everything with:

pacman -Q open-vm-tools
systemctl is-enabled vmtoolsd
systemctl is-active vmtoolsd

My results showed:

open-vm-tools 6:13.1.0-3
enabled
active

VMware Tools was installed and operating correctly.

Discovering an Outdated Omarchy Guide

The VMware workaround I was following had been written for an older Omarchy configuration.

It recommended editing:

~/.config/hypr/envs.conf
~/.config/hypr/monitors.conf

Omarchy 4, also known as Omarchy Quattro, has moved most of its Hyprland configuration to Lua. When I attempted to view monitors.conf, Omarchy reported:

cat: monitors.conf: No such file or directory

Listing the configuration directory revealed the new files:

autostart.lua
bindings.lua
envs.conf
hyprland.lua
input.lua
looknfeel.lua
monitors.lua

The correct Omarchy 4 monitor configuration was now:

~/.config/hypr/monitors.lua

This version difference explained why the older Step 6 had not worked.

Correcting the Display Scaling

The original monitors.lua contained:

local omarchy_gdk_scale = 2
local omarchy_monitor_scale = "auto"

These defaults are designed for modern high-resolution, retina-class displays. Inside my VMware window, they produced the oversized terminal and enormous pointer.

For a normal 1080p-style virtual display, both settings needed to be 1.

I changed the GDK scale with:

sed -i '/gdk_scale/s/2/1/' ~/.config/hypr/monitors.lua

I changed the monitor scale with:

sed -i '5c local omarchy_monitor_scale = 1' ~/.config/hypr/monitors.lua

The final settings became:

local omarchy_gdk_scale = 1
local omarchy_monitor_scale = 1

Hyprland reloaded the monitor configuration immediately. The huge pointer disappeared, and the terminal returned to a normal size.

The official Omarchy documentation also recommends 1x scaling for 1080p and 1440p displays, so this was appropriate for the VMware virtual monitor.

Enabling Software Rendering

The remaining problem was the black desktop background.

The older guide suggested this Hyprland setting:

env = LIBGL_ALWAYS_SOFTWARE, 1

I first added it to envs.conf, but Omarchy 4 did not load that older configuration file during startup. After rebooting, the desktop was still black.

Omarchy 4’s main user configuration is:

~/.config/hypr/hyprland.lua

The file specifically indicates that personal Hyprland configuration can be added at the bottom. Omarchy 4 expresses environment variables through the hl.env() Lua function.

I therefore added the Omarchy 4 equivalent:

hl.env("LIBGL_ALWAYS_SOFTWARE", "1")

I used:

cd ~/.config/hypr
echo 'hl.env("LIBGL_ALWAYS_SOFTWARE", "1")' >> hyprland.lua

I verified it with:

tail -n 3 hyprland.lua

The final line appeared correctly:

hl.env("LIBGL_ALWAYS_SOFTWARE", "1")

I then rebooted the Omarchy VM:

systemctl reboot

Success

This time, Omarchy started with its complete graphical desktop.

The black screen was gone. The enormous pointer was gone. Hyprland’s top bar, workspace indicators, notifications, wallpaper, and desktop elements all rendered correctly.

The final working combination was:

VMware 3D acceleration: Enabled
Graphics memory: 256 MB
open-vm-tools: Installed and running
GDK scale: 1
Monitor scale: 1
LIBGL_ALWAYS_SOFTWARE: Enabled through hyprland.lua

The critical Omarchy 4 configuration was:

-- ~/.config/hypr/monitors.lua
local omarchy_gdk_scale = 1
local omarchy_monitor_scale = 1

And:

-- Added to ~/.config/hypr/hyprland.lua
hl.env("LIBGL_ALWAYS_SOFTWARE", "1")

Recovering the VM After a Host Crash

During troubleshooting, my Debian graphical session became unstable and the computer eventually required a reboot.

After restarting Debian, Omarchy was no longer listed in VMware Workstation’s library. Fortunately, the virtual machine had not been deleted. Only its VMware library registration had disappeared.

I located the VM configuration with:

find ~ -maxdepth 4 -type f -iname '*.vmx' 2>/dev/null

The Omarchy configuration was still present:

/home/lvydvy/vmware/Omarchy/Omarchy.vmx

Opening that .vmx file restored the existing Omarchy virtual machine to VMware Workstation. The virtual disk and installation were intact.

This was another useful reminder: a missing VMware library entry does not necessarily mean that the underlying virtual machine has been lost.

Useful Omarchy Shortcuts

These are the first shortcuts I learned:

Super + Enter    Open a terminal
Super + K        Display the keyboard-shortcut cheat sheet
Super + Space    Open the Omarchy menu

Omarchy is designed around keyboard navigation, so learning the shortcuts is an important part of becoming comfortable with it.

What I Learned

This installation became more than a simple experiment with another Linux distribution.

I learned that:

• Omarchy is based on Arch Linux and uses the Hyprland Wayland compositor.
• VMware can run Omarchy, but graphical compatibility requires workarounds.
• VMware keyboard shortcuts can accidentally reach the Debian host.
• Super + Enter can open a terminal even when the rest of the desktop is black.
• Omarchy 4 replaced several older Hyprland .conf files with Lua configuration.
• Instructions written for earlier Omarchy releases may need to be translated into the new Lua syntax.
• VMware Tools must be installed, enabled, and running.
• Omarchy’s default 2x display scaling is inappropriate for a conventional VMware display.
• A missing VMware library entry does not necessarily mean the VM was deleted.
• Patient verification is safer than blindly repeating installation steps.

Most importantly, I now have a functioning Omarchy 4 environment where I can explore Hyprland, keyboard-driven Linux workflows, terminal tools, development environments, themes, and the broader Omarchy experience without replacing my dependable Debian installation.

What began as a black screen ended with one of the most colorful desktops in my home lab.