omarchy-on-cachyos

An installation script to run DHH's Omarchy on top of CachyOS.

Omarchy is an opinionated Hyprland-based desktop that emphasizes simplicity and productivity. CachyOS is a performance-optimized Arch Linux derivative with custom-patched kernels. This script bridges the two.

---

What This Script Does

1. Clones Omarchy from github.com/basecamp/omarchy.
2. Patches Omarchy's install scripts for CachyOS compatibility.
3. Launches Omarchy's own install.sh.
4. Configures NVIDIA drivers automatically (auto-detects the correct driver branch).

What This Script Does NOT Do

• Install CachyOS or any operating system.
• Partition, format, or encrypt disks.
• Install or configure a bootloader.
• Install or configure a login display manager.

All of the above must be done during your CachyOS installation.

---

Design Philosophy

The goal is a stable blend of CachyOS and Omarchy that changes as little as possible between the two. Conflicts are resolved in favor of CachyOS defaults, with these exceptions:

Component	CachyOS default	Omarchy default	This script chooses
AUR helper	paru	yay	yay (Omarchy's tooling requires it)
Shell	fish	bash	fish (CachyOS default kept)
TLDR impl.	tealdeer	tldr	tealdeer (CachyOS's Rust implementation)
Mise activation	—	bash only	bash + fish (both supported)
NVIDIA drivers	open modules	—	auto-detect (see NVIDIA section)
Display manager	SDDM	none (LUKS-only)	existing DM preserved
Full disk encryption	optional	required	user's choice preserved
WiFi backend	wpa_supplicant	iwd	iwd (Omarchy requires it)

---

Prerequisites

This script does not install CachyOS. Install it first from cachyos.org.

Required CachyOS install choices

Choice	Required value	Why
Filesystem	BTRFS + Snapper	Required by Omarchy
Default shell	fish	Required by this script
Desktop environment	None or Hyprland	Do not install GNOME or KDE
NVIDIA drivers	Let CachyOS auto-install	This script handles reconfiguration if needed

---

NVIDIA Driver Handling

This script auto-detects the correct NVIDIA driver branch using CachyOS's chwd tool:

GPU Architecture	Driver Selected
Turing / Ampere / Ada / Blackwell (RTX 2000+)	nvidia-open-dkms (open kernel modules)
Maxwell / Pascal / Volta (GTX 900–1000, Titan V)	nvidia-dkms-580xx (proprietary)
Kepler (GTX 600–700)	nvidia-dkms-470xx

Override: Set NVIDIA_PROFILE=nvidia-dkms-580xx ./install-omarchy-on-cachyos.sh to force a specific profile.

PRIME (hybrid GPU laptops): Automatically detected. The .prime variant of the profile is selected when an integrated GPU is also present.

NVIDIA + Wayland environment variables configured

These are set in ~/.config/uwsm/env (sourced by UWSM at session start):

LIBVA_DRIVER_NAME=nvidia        # VA-API backend for hardware video decode
__GLX_VENDOR_LIBRARY_NAME=nvidia # GLX vendor selection
NVD_BACKEND=direct              # NVDEC direct backend (driver 555+)
MOZ_DISABLE_RDD_SANDBOX=1       # Firefox NVDEC sandbox workaround
ELECTRON_OZONE_PLATFORM_HINT=auto # Electron apps prefer Wayland
SDL_VIDEODRIVER=wayland         # SDL2 apps use Wayland

Hardware video decode in browsers

Chromium/Chrome: Add to ~/.config/chromium-flags.conf:

--enable-features=VaapiOnNvidiaGPUs

Install the enhanced-h264ify extension and disable VP8 and AV1 codecs.

Firefox: Install the enhanced-h264ify add-on and disable VP8/AV1. Add to user.js:

user_pref("media.hardware-video-decoding.force-enabled", true);
user_pref("media.hardware-video-encoding.force-enabled", true);
user_pref("media.ffmpeg.vaapi.enabled", true);
user_pref("media.rdd-ffmpeg.enabled", true);
user_pref("widget.dmabuf.force-enabled", true);

---

Installation

# Clone this repo
git clone https://github.com/mroboff/omarchy-on-cachyos.git
cd omarchy-on-cachyos/bin

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

# Run (verbose mode recommended for first install)
VERBOSE=1 ./install-omarchy-on-cachyos.sh

Review the script before running. It makes system-wide changes.

Environment variables

Variable	Default	Description
VERBOSE	0	Set to 1 for debug output
OMARCHY_REPO	https://github.com/basecamp/omarchy	Omarchy git URL
OMARCHY_DIR	~/omarchy	Where to clone Omarchy
NVIDIA_PROFILE	auto	Force a specific chwd NVIDIA profile
LOG_FILE	~/.local/share/omarchy-on-cachyos/install.log	Log file location

Flags

Flag	Description
--verbose	Enable debug output (same as VERBOSE=1)
--skip-omarchy-clone	Skip cloning Omarchy (use existing ~/omarchy)

---

Post-Install: No Display Manager?

If you installed CachyOS without a desktop environment (minimal install), no display manager is installed. After the script completes, run:

~/.local/share/omarchy/install/login/plymouth.sh

This configures Hyprland to start automatically at boot via UWSM/systemd.

---

Troubleshooting

Log file: ~/.local/share/omarchy-on-cachyos/install.log

WiFi connects but has no IP / no internet

CachyOS starts wpa_supplicant by default, which conflicts with Omarchy's iwd. The install script disables wpa_supplicant and sets NetworkManager to use iwd. If you still have issues:

sudo systemctl disable --now wpa_supplicant.service
sudo systemctl enable --now iwd.service

Then set wifi.backend=iwd in /etc/NetworkManager/NetworkManager.conf under [device].

NVIDIA: screen flickering or no hardware acceleration

1. Check driver version: pacman -Q nvidia-utils
2. Check active chwd profile: chwd --list-installed
3. Verify VA-API: vainfo
4. Check env vars are set: env | grep -E 'LIBVA|NVD|GLX'
5. Try forcing 580xx proprietary: NVIDIA_PROFILE=nvidia-dkms-580xx ./nvidia.sh

Walker launches wrong version

The install script pins walker to the Omarchy repo in IgnorePkg. Verify:

grep IgnorePkg /etc/pacman.conf

Re-running the install script

The script is idempotent — safe to re-run. Patches check for existing content before applying. The Omarchy clone is updated (fast-forward pull) rather than re-cloned.

---

Compatibility

Component	Tested version	Notes
CachyOS	2025+	Rolling release
Kernel	linux-cachyos 7.x	Also works with linux-cachyos-lts
Omarchy	3.0+
NVIDIA driver	555+ (open), 580xx (proprietary)	Auto-detected
Hyprland	Current	Via Omarchy
UWSM	Current	Via Omarchy
PipeWire	Current	CachyOS default, no changes
NetworkManager	Current	iwd backend configured

---

Contributing

1. Fork the repository.
2. Create a feature branch: git checkout -b feature/your-feature.
3. Test on a real CachyOS installation before submitting.
4. Open a pull request with a clear description.

Report bugs via GitHub Issues.

---

License

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND. Use at your own risk. Always back up your system before running installation scripts.