omarchy-on-cachyos patches a desktop setup onto a performance tuned Arch

Four jobs, and four things it refuses to touch

Omarchy is DHH's opinionated desktop setup, built on Hyprland, and this repository is an installation script that puts it on top of CachyOS, a performance optimized Arch Linux distribution. The README describes the project as aimed primarily at the experienced Arch Linux user, and it says the author assumes the reader is comfortable with a shell and familiar with Arch specific terms such as the AUR.

The script does four things. It prompts for and fetches a version of Omarchy, either a stable tag or bleeding edge, with interactive version selection added in a May 2026 update. It adjusts the Omarchy install scripts so they work on CachyOS. It then launches the installation of Omarchy on a system that is already set up. Finally, it installs and configures NVIDIA 580xx proprietary drivers.

The list of what it does not do is just as important, and it is short enough to memorise. It does not install CachyOS or any other operating system. It does not partition, format or encrypt hard disks. It does not install or configure a boot loader. And it does not install or configure a login display manager. The README states that all of those need to be done when you install CachyOS itself.

That division of labour is the whole design. You arrive with a working, bootable, encrypted Linux system, and the script layers the desktop on top. Anyone hoping for a one command install from a blank disk is reading the wrong repository.

Three default conflicts the script has to pick a side on

The stated philosophy is to produce a blend of CachyOS and Omarchy that changes as little as possible on either side. The script does not add software or make configuration changes outside what the two projects provide by default, except where the two are in conflict. In those cases it makes explicit choices, and it lists them.

The first is the AUR helper. CachyOS uses Paru by default, Omarchy uses Yay, and this script opts for Yay, installing it if it is not already there. The second is the shell. CachyOS uses Fish by default, Omarchy uses Bash, and the script keeps Fish as the default interactive shell, which is consistent with the prerequisite that you install CachyOS with Fish chosen.

The third is the TLDR implementation. CachyOS installs Tealdeer by default, a TLDR implementation written in Rust, and the script preserves its use rather than letting Omarchy replace it. The fourth item is Mise. Omarchy sets up Mise to run automatically through mise-activate, and the script supplies the right mise-activate command for the fish shell, which is the small adjustment needed because the two projects disagree about the shell.

These are small decisions individually, but they are the kind that quietly break a desktop when two opinionated projects meet. A wrong mise-activate command means your tool versions silently stop loading in Fish, and nothing warns you about it.

Hyprland autostart and LUKS are the two assumptions that change

Omarchy is a distribution, and two of its behaviours are described as automatic in a way that does not hold on CachyOS.

The first is the login system. As a distribution, Omarchy skips installing a login display manager entirely, and instead Hyprland autostarts, with password protection provided on boot by the LUKS full disk encryption service. This script assumes a display manager is installed instead. The README is careful about the consequence: the script does not install a display manager, and it also does not configure Hyprland to start automatically if a display manager is not installed. So on a system where you chose a minimal install with no desktop environment and no display manager, you get a system with Hyprland installed and no way to reach it at boot.

The second is full disk encryption. Omarchy as a distribution turns on LUKS automatically. This script leaves that decision to you, and it works on a CachyOS system installed with or without full disk encryption.

That asymmetry is worth understanding before you run anything. Encryption is a decision the script defers, but the display manager assumption is a decision the script makes for you, and it is the one that produces a machine that boots to a black screen. The README's guidance is to install the CachyOS Hyprland desktop environment, which brings SDDM as the login display manager by default, and explicitly not to install GNOME or KDE.

NVIDIA drivers are pinned to the proprietary 580xx series

The driver handling is the most opinionated part of the script and the one with the clearest rationale. By default, the README says CachyOS and Omarchy may attempt to use the latest NVIDIA drivers with open kernel modules. The script explicitly downgrades and pins the driver to the 580xx proprietary series using CachyOS's chwd tool, and the stated reason is to fix widespread issues with hardware acceleration, electron apps and browser flickering.

So this is not a preference for proprietary drivers as such. It is a pinning decision aimed at a set of concrete regressions in the newer open kernel module drivers, including known problems with hardware video decoding and browser flickering. The script runs the driver installation automatically, so you do not have to make that call yourself.

The README then adds a section on getting hardware acceleration actually working, and it is manual from there. For Chromium, hardware video decode through NVDEC requires adding flags to ~/.config/chromium-flags.conf, specifically the VaapiOnNvidiaGPUs feature, plus installing the enhanced-h264ify extension and disabling the VP8 and AV1 codecs. For Firefox, you install the equivalent add-on, disable VP8 and AV1, and set a block of preferences in user.js.

Those user.js settings force hardware video decoding, hardware video encoding, layer acceleration, WebGL, the media ffmpeg VAAPI path and the dmabuf path. The AV1 preference in that list sits in tension with the instruction to disable AV1 codecs, and the README does not explain the interaction. That is a detail to test on your own machine rather than assume.

The prerequisites are a specific CachyOS install, not any install

The script is explicit that it does not install CachyOS and must be run on a fresh installation that was configured in a particular way. There are three requirements, and each one is load bearing.

The filesystem must be BTRFS with Snapper as the snapshot manager, which the README describes as aligning with the CachyOS default recommendation for most systems and as required for Omarchy to properly function. The default shell must be Fish, which the script needs both because the install targets it and because the mise-activate adjustment is fish specific. The desktop environment is a choice: a minimal system with no desktop environment is possible, or you install the CachyOS Hyprland desktop environment, which also installs SDDM as the login display manager by default. The README rules out GNOME and KDE.

The rest of the configuration is left to you, with the caveat that the script has not been extensively tested on CachyOS installations other than the author's own machine. That sentence is the honest signal about the confidence level of the whole project, and it belongs in your decision rather than in a footnote.

The project is MIT licensed, and the repository includes the README, a LICENSE file, a bin/ directory holding the install script, and a github/ directory. The primary language is recorded as Shell, which matches a project that is essentially one script plus its documentation.

Running the install, and reading it first

The installation instructions are four steps, and the first one is to get the script onto your machine:

# Clone the repository
git clone https://github.com/mroboff/omarchy-on-cachyos.git

# Navigate to the project directory
cd omarchy-on-cachyos/bin

# Make the script executable
chmod +x install-omarchy-on-cachyos.sh

# Run the installation script
./install-omarchy-on-cachyos.sh

The script lives in bin/, and the steps are clone, change into that directory, make the file executable and run it. When it starts, it prompts for which Omarchy version you want, stable tags or bleeding edge, and then it fetches that version, adjusts the Omarchy install scripts for CachyOS, and launches the installation.

The README's own advice is to review the script contents before running it, to understand what changes will be made to your system. For a script that installs a desktop environment, configures a display manager dependency, pins kernel level drivers and modifies your shell setup, that is not a formality. The script is short enough to read end to end, which is one of the practical advantages of a project this size.

The release history is minimal. Two tags exist, omarchy_on_cachyos_1.0 for the Omarchy 2.x install method and omarchy_on_cachyos_2.0 for the Omarchy 3.0+ method, both published on 2025-10-02, and the README notes an update on 1 October 2025 that made the script support Omarchy 3.0 out of the box. The most recent push was on 2026-06-01, which is the commit that added interactive version selection.

A community script, a warranty disclaimer and one tested machine

Two documents in this repository matter more than the feature list.

The first is the statement of lack of warranty, which is the standard broad disclaimer that the software is provided as is, without warranty of any kind, express or implied, including the merchantability and fitness for a particular purpose clauses, and that in no event shall the authors be liable. It is the normal text for a script of this kind, and it is also a plain statement of the relationship: there is no support commitment here, and no one is promising your system will boot afterwards.

The second is the sentence about testing. The script has not been extensively tested on CachyOS installations other than the author's own machine, which tells you that the supported configuration is one specific setup. If your CachyOS install differs in filesystem, snapshot manager, shell or desktop environment, you are outside what has been exercised, and the failure mode is likely to be a half configured desktop rather than a clean error.

The alternative is to install Omarchy on a plain Arch Linux base, where the conflicts this script exists to resolve mostly do not exist: the AUR helper, the shell and the TLDR tool are the ones the script had to arbitrate, and on a base system that matches Omarchy's expectations there is nothing to arbitrate. The trade is that you give up the CachyOS performance profile, which is the reason most people running this script are running CachyOS in the first place.

There is also the route of installing CachyOS with its own Hyprland environment and leaving Omarchy out. The README assumes a display manager is present and Hyprland is available, which is close to the shape of that setup, and the difference is that you keep the CachyOS defaults rather than a hybrid of both projects.

Editorial conclusion

Adopt omarchy-on-cachyos if you already run CachyOS with BTRFS, Snapper and Fish as the default shell, you want the Omarchy Hyprland desktop without reinstalling your base distribution, and you are comfortable editing the script before running it. Do not adopt it if you want a supported path, since this is a community script with a statement of lack of warranty, or if your system is not already installed and configured, since it refuses to install CachyOS, partition disks, install a boot loader or set up a display manager. Before running it, confirm your filesystem is BTRFS with Snapper, check that your shell is Fish, and read bin/install-omarchy-on-cachyos.sh, since the last push was on 2026-06-01 and the README states the script has not been extensively tested outside the author's own machine.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mroboff/omarchy-on-cachyos on GitHub
4. README
5. Releases