The Omarchy look on CachyOS without reinstalling: what changed and old guides don't tell you

Omarchy is a very slick Linux setup built on Hyprland, a tiling window manager with smooth animations. It’s become very popular, and I wanted that look on my laptop.

The problem: my laptop runs CachyOS (an Arch-based, heavily optimised distribution) and I didn’t want to reinstall. I also have KDE Plasma and wanted to keep it as a fallback.

I managed it, but along the way I discovered that almost everything you read online about Omarchy is out of date. Here’s what changed.

What’s no longer true in Omarchy 4

• It no longer installs on top of Arch. There used to be a script you ran on a fresh Arch install. Now Omarchy installs from its own ISO, and its package list says so plainly.
• It doesn’t use Waybar. The top bar and widgets are Quickshell. If a guide tells you to edit the Waybar config, it’s old.
• It doesn’t use wofi. The app launcher is walker (with its elephant service).
• The Hyprland config is Lua, not the usual .conf format. Recent Hyprland versions (0.56 onwards) support Lua config out of the box.

With that clear, the plan changes quite a bit.

The Omarchy repository

Omarchy has its own signed pacman repository. To use it you install its keyring and, also, tell pacman to trust it:

sudo pacman -U omarchy-keyring-*.pkg.tar.zst
sudo pacman-key --populate omarchy

If you skip the second command, pacman fails with an error along the lines of “signature is of unknown trust”. It took me a while to spot.

What I installed (and what I didn’t)

I installed the pieces: hyprland, quickshell, walker, elephant and their dependencies.

What I didn’t install is the omarchy package itself. Why? Because it adds a pacman hook: a script that runs on every install or update of any package on the system. For a full distribution that makes sense; for someone who only wants the look, it’s too invasive.

Instead, I cloned the Omarchy repository into my home folder:

git clone https://github.com/basecamp/omarchy ~/.local/share/omarchy

It has the same layout it would have if installed system-wide, including the hundreds of scripts in its bin/ folder. And by keeping the .git folder, I can update it with git pull whenever I like.

Environment variables

So everything finds its pieces, two things in ~/.config/environment.d/omarchy.conf:

OMARCHY_PATH=$HOME/.local/share/omarchy
PATH=$PATH:$HOME/.local/share/omarchy/bin

Note that Omarchy’s bin/ goes at the end of PATH, never the start. There are hundreds of scripts, and if one shared a name with a system command, it would shadow it. At the end of PATH, the system one takes priority.

The theme

The active theme is a symlink to one of the theme folders. I chose Tokyo Night:

~/.local/state/omarchy/current/theme → .../themes/tokyo-night

Switching themes means changing that link (Omarchy ships scripts for it).

Starting the session

The login screen now offers Hyprland (uwsm) as well as Plasma. I pick one or the other depending on the day. Plasma is untouched: if something breaks in Hyprland, I log out and use Plasma.

Tip before you log out

With a Lua config, a syntax error or a require() pointing to a file that doesn’t exist can leave you with a broken session. Before trying it, check that every file the config loads actually exists. Much nicer than finding out with a black screen.

Is it worth it?

If you like working from the keyboard with tiled windows, yes: it’s fast and gorgeous. But if you set it up by hand on another distribution, accept that you’re the one maintaining the pieces. And be wary of any guide that doesn’t say which version it’s about.