Omarchy Linux 4: A Developer's Guide to the Arch Desktop

Introduction

Anyone who has built an Arch + Hyprland desktop by hand knows the ritual: a weekend of wiki tabs, dotfile archaeology, and a status bar that works right up until the next compositor update. Omarchy, created by Ruby on Rails author David Heinemeier Hansson (DHH), skips the ritual by shipping every decision pre-made. Compositor, shell, terminal, themes, editor, and even a default AI coding agent come configured out of the box.

This article covers what Omarchy 4 (“Quattro”) is made of, how its update and rollback model works, how to install it without losing data, and where it can hurt. It’s written for developers deciding whether to put it on a daily-driver machine, not for first-time Linux users.

One caution about currency: the project shipped five point releases in the two months after Quattro landed on August 14, 2026. The latest at the time of writing is 4.0.5 (October 18, 2026). Check the release page before relying on any version-specific detail below.

ℹ️ Prerequisites

You should be comfortable with the terminal and with partitions, LUKS disk encryption, and bootloaders. You'll need an x86_64 machine, a USB stick, a verified backup of anything on the target disk, and the ability to change UEFI firmware settings (Secure Boot and/or TPM). A wired or 2.4 GHz dongle keyboard is safest for the LUKS encryption prompt at boot, because Bluetooth keyboards generally don't work that early in the boot process.

What Omarchy Is (and Isn’t)

Omarchy is an Arch-based distribution that bundles the Hyprland tiling compositor, a custom desktop shell, and a curated set of developer tools into one opinionated package. DHH released it on June 26, 2025, and it grew from a post-install configuration script into a full distribution with its own ISO and package repository. The project’s own manual describes the philosophy as omakase: you don’t order, the chef decides.

That is the core trade-off. You get a coherent, fast-to-productive environment, and you give up the granular freedom that draws many people to vanilla Arch in the first place.

June 2025

Initial release

An opinionated Arch + Hyprland setup, announced by DHH as a turnkey developer environment.

May 2026 — Omarchy 3.7

One CLI to rule the scripts

A unified omarchy command puts one front door on a sprawl of separate omarchy-* scripts.

August 14, 2026 — Omarchy 4.0

The Quattro release

Entire desktop shell rebuilt on Quickshell; internals move from a local git checkout to system packages.

September–October 2026 — 4.0.3 to 4.0.5

Agents, kernel, hardening

OpenClaw and Hermes integrations, a bespoke linux-omarchy kernel, Qt 6.12, and Linux 7.2.8 with the BORE scheduler.

Core Concept 1: One Shell Process Instead of Many Tools

Before Quattro, an Omarchy desktop was a bundle of small, separate programs: Waybar, Walker, Mako, SwayOSD, hyprlock, hypridle, swaybg, and polkit-gnome. Quattro replaced all of them with a single long-running Quickshell process. The bar, launcher, menus, notifications, on-screen displays, control panels, lock screen, and polkit agent now run as plugins inside it.

This architecture has practical consequences:

Consistent theming. Every surface is driven by the same theme data, and Quattro expanded the base theme palette from 8 to 24 colors so editor and monitor themes (Neovim, VS Code, btop) can be generated rather than hand-maintained.
Lower idle cost. The shell is event-driven rather than polling, so an idle desktop does less background work.
Extensibility. Third-party bar widgets, or entire replacement bars, install straight from a git URL with omarchy plugin add <git-url>.
One menu. Super + Space opens a filterable, nested command palette that merges app launching with system commands. Super + Alt + Space opens an apps-only menu.

ℹ️ Why "packages instead of git" matters

Quattro moved Omarchy's internals from a mutable git checkout in your home directory into system-managed packages, specifically to keep your modifications separate from shipped files. The practical rule: treat the installed Omarchy system tree as read-only and put every customization in your own config under ~/.config. Changes made inside the shipped tree can be overwritten by updates.

Two packaging details from the 4.0.x line are worth knowing. Omarchy’s bespoke linux-omarchy kernel became the default boot option in 4.0.4, and 4.0.5 moved it to Linux 7.2.8 with the BORE (Burst-Oriented Response Enhancer) scheduler, aimed at keeping the desktop responsive under heavy load or memory pressure. Release 4.0.5 also prioritizes Omarchy’s own package repository over Arch’s.

Core Concept 2: Channels, Updates, and Snapshots

Omarchy updates along four channels. New installs start on stable, which tracks official releases and uses a snapshot of the Arch mirror that runs about a month behind upstream, so package incompatibilities that require config changes get caught before they reach you. RC is used for final validation before major releases, edge is for testers willing to catch regressions early with newer packages, and dev tracks the very latest Omarchy code changes alongside edge packages. The manual reserves dev for contributors working on Omarchy itself who can tolerate routine breakage.

The update command is more than a package download. It handles Omarchy’s own release packages, system packages, config migrations, and a pre-update Btrfs snapshot as one coordinated flow:

If an update goes wrong, you reboot, pick a pre-update snapshot in the Limine boot menu, and trigger the restore from the desktop notification that appears (or via the omarchy snapshot CLI command group).

ℹ️ What snapshots do and don't cover

Because Omarchy uses separate Btrfs subvolumes for the root filesystem and user data, restoring a snapshot reverts / (system packages and configs) without touching /home. It cleanly fixes a broken system update, but it will not recover deleted personal files or broken dotfiles in ~/.config—so keep real backups. Snapshot booting also requires the Limine bootloader (the default since Omarchy 2.0) and is not available on GRUB or systemd-boot setups.

Practical Implementation: Installing Omarchy

Back up and choose a layout

Full-disk installs wipe the selected drive and enable LUKS encryption with Btrfs by default. Quattro also supports dual-booting from unallocated free space on the same disk: shrink your Windows volume in Disk Management first, and disable BitLocker before resizing, as the dual-boot guide notes BitLocker is incompatible with the default installer flow.

Download and verify the ISO

Fetch the ISO from iso.omarchy.org and verify its integrity against the 64-character SHA256 checksum published on the official GitHub release page before flashing.

Flash a USB stick

The manual recommends balenaEtcher on macOS and Windows and caligula on Linux; plain dd also works if you are careful with the target device.

Adjust firmware settings

The installation guide says you must turn off Secure Boot and/or TPM in your UEFI/BIOS settings before the installer will work. Framework's guide adds that Omarchy does not support Secure Boot by default, although it can be configured to.

Install and verify first boot

Boot the USB stick, select the target drive or free space, and let the installer run. After rebooting, confirm the LUKS encryption prompt accepts your keyboard and, for dual-boot setups, that Windows appears in the Limine boot menu. If Windows is missing, run limine-scan to detect and add it.

# Omarchy 4.0.5 ISO (released 2026-10-18)
curl -LO https://iso.omarchy.org/omarchy-4.0.5.iso

# Verify against the 64-character SHA256 from the GitHub release page
echo "73fd4334f1f67b19cd8a5589f9363173fc3aec07c0a59f198833eaddb66877a1  omarchy-4.0.5.iso" | sha256sum -c -
# Expected output: omarchy-4.0.5.iso: OK

# Flash on Linux with caligula (use balenaEtcher on macOS/Windows)
caligula burn omarchy-4.0.5.iso

⚠️ Conflicting dual-boot documentation

The manual's "Getting Started" page still states that dual-booting requires two separate physical disks unless you perform a manual Arch install. However, the dedicated "Dual Boot Install" page confirms Quattro can install into unallocated space alongside Windows on a single drive. While the newer page reflects Quattro's updated installer, treat any single-disk dual-boot attempt as an operation that requires a verified image backup beforehand.

The omarchy command is the front door to everything that was previously a collection of standalone omarchy-* scripts. It is self-describing, which makes it friendly both to shell scripting and to AI coding agents:

omarchy commands            # list every command, grouped
omarchy commands --json     # machine-readable list for scripts and agents
omarchy theme list          # show available themes
omarchy theme set <name>    # apply a theme (pick <name> from the list)
omarchy update              # coordinated update: snapshot, packages, migrations
omarchy <group> --help      # e.g. omarchy channel --help

Your personal configuration lives in user-owned files, ensuring system updates can replace shipped defaults without overwriting your customizations:

Path	Purpose
`~/.config/hypr/bindings.lua`	Personal keybindings (Hyprland user configs use Lua in Quattro)
`~/.config/omarchy/shell.toml`	Machine-level overrides merged over the active theme, so font, spacing, or bar tweaks survive theme switches
`~/.config/omarchy/extensions/omarchy-menu.jsonc`	Extend the Omarchy menu (`Super + Space`) with custom entries
`~/.config/starship.toml`	Shell prompt configuration

Community documentation also describes lifecycle hooks under ~/.config/omarchy/hooks/. A minimal post-update hook looks like this (confirm the exact hook directory structure against your installed version, as this layout comes from community-generated repository docs rather than the official manual):

mkdir -p ~/.config/omarchy/hooks/post-update.d
cat > ~/.config/omarchy/hooks/post-update.d/log-update <<'EOF'
#!/usr/bin/env bash
# Append a timestamp each time `omarchy update` finishes
mkdir -p ~/.local/state
echo "$(date -Is) omarchy update completed" >> ~/.local/state/omarchy-updates.log
EOF
chmod +x ~/.config/omarchy/hooks/post-update.d/log-update

For developers working with AI tooling, Quattro treats coding agents as first-class citizens. You can select a default agent under Setup > Defaults > Agent (Claude Code, Codex, OpenCode, Pi, Gemini, Copilot, and others), launch it anytime with Super + Shift + Ctrl + A, and install agent integrations such as OpenClaw and Hermes from Install > AI. A built-in bar widget tracks model usage across the major harnesses. As a safety improvement, version 4.0.1 changed default Claude and Codex launches to use auto-review mode rather than a blanket permission bypass.

Footprint

<6 GB

ISO Size

Shrunk by over a gigabyte in Quattro (official release notes)

14 GB

Disk After First Update

One reviewer's default install (The Register)

~1.5 GB

Idle Memory

Reported by the same reviewer; your hardware and workload will vary

These figures come from single-reviewer measurements rather than standardized benchmarks, but they underscore an important point: Omarchy is a batteries-included workstation, not a minimal base install.

Omarchy vs. Rolling Your Own Arch + Hyprland

✅ Omarchy

Working, cohesively themed desktop within a single install session
One coordinated update path with automatic pre-update snapshots
Release channels backed by a ~1-month delayed stable mirror
Quickshell plugin ecosystem and a scriptable CLI
Best for: developers who want a productive tiling setup today

✅ DIY Arch + Hyprland

Every component chosen, configured, and understood by you
Smaller disk footprint and standard upstream pacman workflow
Your own security posture, with no inherited opinionated defaults
Zero dependency on a third-party project's migration scripts
Best for: users who want to learn the stack or need total control

Reviewers disagree about which approach wins, and for good reason: the exact same design choice reads as “curated” to fans and “rigid” to critics. One developer reported moving back to vanilla Arch after finding Omarchy frustrating to customize piece by piece, while another found it fast and visually striking despite occasional rough edges.

Common Pitfalls and Troubleshooting

⚠️ Don't update with raw pacman

Omarchy updates rely on pre-update snapshots and config migration steps. The supported flow is omarchy update (or Update → Omarchy in the main menu). Omarchy actively blocks direct full-system upgrades by default and redirects you to its CLI wrapper. Bringing a muscle-memory sudo pacman -Syu habit from vanilla Arch will fight the distribution's design.

⚠️ Disk space gets tight fast

One reviewer installed Omarchy into a 16 GB virtual disk and immediately ran out of room during the first system update. Give VMs and dual-boot partitions significantly more breathing room than the base 14 GB footprint suggests—Btrfs snapshots, Docker images, and pacman package caches accumulate quickly.

⚠️ Documentation drift

Omarchy moves fast and documentation often lags behind code. Parts of the official manual still reference pre-4.0 shortcuts, and any community tutorial that tells you to edit Waybar, Walker, or Mako config files predates Quattro's unified Quickshell architecture. When a guide and your machine disagree, trust omarchy commands and the GitHub release notes for your installed version.

🚨 Know the security debate before you commit

Critics, including a security-focused blog post and a Framework community forum thread, argue that Omarchy is not a secure distribution. The project now has a dedicated security team and has shipped a wave of hardening across 4.0.1 through 4.0.5: signed packages are now required from the Omarchy repository, SSH password authentication is disabled by default, and adding your user to the docker group is opt-in rather than automatic. However, installation still requires turning off Secure Boot out of the box (Framework's guide notes Omarchy can be configured to support it afterwards). Evaluate these trade-offs against your own threat model.

🚨 Plugins run code inside your shell process

Running omarchy plugin add <git-url> pulls third-party code directly into the Quickshell process that also manages your lock screen and authentication prompts. Recent 4.0.x point releases hardened plugin handling with git URL validation and restricted access to authentication services, but you should still audit a plugin's repository before installing it.

A few smaller hardware and UX quirks to keep in mind:

No window chrome: The interface deliberately omits title bars and close/minimize buttons, so budget an afternoon to internalize the keyboard shortcuts.
Multi-monitor setups: One reviewer needed an external utility to configure a second monitor properly, though Quattro includes a native Display panel (Super + Ctrl + D) that may cover most layouts, so test your own setup.
Hybrid NVIDIA laptops: The installer should detect NVIDIA GPUs and install the appropriate driver, but Framework’s installation guide for the Laptop 16 notes you may need to add the NVIDIA kernel modules to early KMS (initramfs) if the display manager starts before the GPU driver finishes initializing.

Finally, be aware that Omarchy and its founder attract strong opinions in the wider Linux community that go beyond technical merits. Independent press coverage discusses the surrounding ecosystem and funding context at length, which is worth reading if long-term project governance matters to your workflow.

Conclusion

Omarchy 4 is best understood as an integrated product rather than a DIY base: Arch’s rolling ecosystem and Hyprland’s speed, wrapped in a unified Quickshell desktop, a scriptable CLI, and a snapshot-backed update pipeline. Quattro’s shift from a local git checkout to system packages and a single shell process is designed to make updates safer by separating shipped files from your own changes, even if the rapid cadence of 4.0.x point releases shows the dust is still settling. It richly rewards developers who embrace its omakase defaults, and quickly frustrates those who want to rebuild the kitchen.

💡 Next Steps

Test Omarchy on a spare SSD or secondary laptop before committing your primary workstation. After installing, run omarchy commands to explore the CLI, verify you can boot into the Limine snapshot menu before running your first update, and set up automated off-disk backups for /home. Finally, watch or RSS-subscribe to the official GitHub releases page so you catch security and point-release notes as they land.

References:

Omarchy releases (v4.0.0 “Quattro” through v4.0.5) - https://github.com/omacom/omarchy/releases - Feature lists, ISO checksums, kernel, shell, packaging, and security changes.
The Omarchy Manual: Updates - https://learn.omacom.io/2/the-omarchy-manual/68/updates - Four release channels, the update flow, and rollback.
The Omarchy Manual: System Snapshots - https://learn.omacom.io/2/the-omarchy-manual/101/system-snapshots - Snapshot restore scope and Limine requirement.
The Omarchy Manual: Getting Started - https://learn.omacom.io/2/the-omarchy-manual/50/getting-started - ISO install, Secure Boot/TPM, encryption defaults.
The Omarchy Manual: Dual Boot Install - https://learn.omacom.io/2/the-omarchy-manual/120/dual-boot-install - Free-space dual boot, BitLocker, Limine.
The Register, “Omarchy distro gains serious backing” - https://www.theregister.com/os-platforms/2026/08/27/omarchy-distro-gains-serious-backing/5293026 - Independent hands-on, footprint figures, criticism, and funding context.
Linuxiac, “Omarchy 4.0.5 Released” - https://linuxiac.com/omarchy-4-0-5-released-with-linux-kernel-7-2-8-better-hardware-support/ - Cross-check of 4.0.5 contents.
Unified CLI pull request (#5467) - https://github.com/omacom/omarchy/pull/5467 (formerly basecamp/omarchy) - The omarchy command groups introduced in 3.7.
Framework Laptop 16 installation guide - https://guides.frame.work/Guide/Omarchy+Linux+Installation+on+the+Framework+Laptop+16/567 - Secure Boot and NVIDIA notes.
Omarchy on Wikipedia - https://en.wikipedia.org/wiki/Omarchy - Release history and current version.
Config surfaces discussion (#11029) - https://github.com/omacom/omarchy/discussions/11029 - Paths for personal configuration files.
LabEx, “How to Update Omarchy and Recover from a Bad Update” - https://labex.io/blog/omarchy-update-rollback - Direct-upgrade guard and snapshot flow (community guide).
Community-generated repository docs - https://instagit.com/omacom/omarchy/how-to-customize-omarchy-user-configuration/ - Hook layout and keyboard note (auto-generated from the repo; verify against the manual).
Omarchy discussion (#3168) - https://github.com/omacom/omarchy/discussions/3168 - Shows the Btrfs + Snapper snapshot setup (written against 3.1.x).