Omarchy: an opinionated Arch-based Linux distribution built around Hyprland

What Omarchy is and who it is aimed at

Omarchy describes itself in the README as "a beautiful, fun & agentic Linux distribution by DHH". That single sentence carries three claims worth separating. It is a distribution rather than a desktop configuration, it is opinionated about how the desktop should look and behave, and it is built on Arch. The repository is mostly Shell, licensed MIT, and its default branch is named quattro. The most recent tagged release is v4.0.3, published on 2026-09-08, and the last push to the repository was on 2026-09-10.

The audience is implied by the manual's table of contents rather than stated outright. There is a chapter called Coming From Mac or Windows, which suggests the project expects people who are not long-time Linux users. There is also a chapter on development tools, one on Neovim and one on AI, which suggests the target reader writes code. The two audiences overlap: a developer who wants a working desktop without spending a weekend on window manager configuration.

What it is not aimed at is equally clear from the layout. There is no graphical settings application listed among the top-level entries. Configuration is handled through files, a CLI and the manual. If you want a distribution where every preference is a checkbox, the manual's structure tells you this is the wrong shape.

The Hyprland foundation and the bundled toolset

Omarchy is built on Hyprland, a Wayland compositor. The related searches people run around this project include both "Omarchy Hyprland" and "Omarchy based on", which suggests the underlying stack is the first thing newcomers try to establish. The manual's Navigation chapter and its chapter on monitors, keyboard, mouse and trackpad cover the compositor-level behaviour you would otherwise configure by hand: workspaces, window rules, input devices and display layout.

Above the compositor, the repository ships a large set of defaults. The top-level entries include applications/, config/, default/, themes/, shell/ and bin/. The manual maps onto those directories: Themes, Hotkeys, the top bar, the Omarchy CLI, shell plugins, shell functions, prompt and branding each get a chapter. The presence of a branding chapter is telling. This distribution treats the look of the system as part of the product, not as something the user is expected to supply.

Themes are a first-class concept rather than a colour scheme you edit by hand. The manual has both a Themes chapter and a chapter on making your own theme, and there is a themes/ directory at the top level. Wallpapers are handled separately according to the related searches, and the manual lists a Backgrounds chapter. The migration directory and the version file at the repository root suggest the project tracks its own state across upgrades, which matters for the update story described later.

Installing Omarchy and running the first commands

The README points to omarchy.org for the project itself and to learn.omacom.io for the manual, where screenshots are hosted. The manual's Getting Started chapter is the entry point, and the repository has an install/ directory. The install command line is not reproduced in the README, so the honest instruction is to follow the manual's Getting Started page rather than copy a command from a review.

Once the system is running, the manual documents an Omarchy CLI in its own chapter. That is the interface you are expected to learn first, because it wraps the settings and actions that would otherwise be scattered across config files. The exact subcommands are not given in the README, so check manual/14-omarchy-cli.md before relying on any command you have seen elsewhere.

What can be shown concretely is the shape of the repository, because that is what you will be editing. The layout puts user-facing configuration in config/, shipped defaults in default/, and the shell environment in shell/:

ls config default shell themes

Reading the manual's Dotfiles chapter before you touch any of those directories is the difference between a system that survives an update and one that fights it. The manual also has a chapter on common tweaks, which is the right place to look before inventing your own approach to a problem the project has already solved.

For people installing on a machine that already has an operating system, the manual covers dual boot install and unattended installs as separate chapters, and there is a chapter on installing on a Mac. Those are the cases where the install procedure diverges most from a plain Arch install, so read the matching chapter rather than the general one.

Updates, dotfiles and the cost of staying current

The manual devotes chapters to updates, dotfiles and system snapshots, and that grouping is the clearest signal of where the maintenance burden sits. An Arch-based distribution inherits rolling releases. That means the update mechanism is not a background service you can forget; the manual's Updates chapter is the authoritative description of how Omarchy expects you to apply changes.

The dotfiles chapter matters because an opinionated distribution has to answer a hard question: what happens to your edits when the project changes a default? The repository separates config/ from default/, and the presence of a migrations/ directory suggests the project handles some transitions itself. The README does not document rollback, and the manual's System snapshots chapter is the place to look for it.

This is the real cost of adoption, and it is worth stating plainly. You are not maintaining a desktop environment with a stable configuration API. You are tracking a project that ships defaults, themes and shell behaviour, and the last push was on 2026-09-10, so defaults are moving. The upside is that someone else is doing the integration work. The downside is that your local modifications live in the path of that work.

Where Omarchy is the wrong choice

The opinionated design is the product, and it is also the limitation. If you already have a Hyprland configuration you have tuned over years, Omarchy's value proposition is negative: you would be replacing your setup with someone else's and then re-applying your changes on top of a moving target. The same applies if you want a minimal Arch install with a window manager and nothing else. The bundled applications, shell functions and prompt are part of the package, not optional extras you can decline at install time.

A second limit is the Wayland compositor itself. Anything that requires X11 behaviour, or a tool that has not been ported, will not work the way it does on a conventional desktop. The manual has a troubleshooting chapter precisely because this class of problem exists.

A third is hardware. The manual covers monitors, networking, system sleep and hardware authentication as separate topics, which reflects the reality that laptops with unusual display setups, fingerprint readers or power management behaviour need per-device attention. A distribution that ships a fixed desktop cannot pre-solve every machine. If your hardware is not covered by the manual's chapters, you are doing the integration yourself, and the opinionated defaults stop being an advantage.

Omarchy against a plain Arch install

The obvious alternative is Arch itself. Arch gives you the base system and the package manager, and nothing else. You choose the compositor, write the configuration, pick the theme, and decide which applications exist. The difference is not quality, it is where the decisions are made. Arch pushes every decision to install time and keeps pushing them as you use the system. Omarchy makes a large set of those decisions in advance and documents them in a manual with roughly fifty chapters.

A second comparison point is a conventional desktop distribution with GNOME or KDE. Those give you a graphical settings application and a configuration model that survives upgrades without you reading release notes. Omarchy does not offer that. Its configuration model is files plus a CLI plus a manual, and the manual is the authoritative source rather than a supplement.

The practical test is simple. If reading a chapter before changing a setting sounds like overhead, Omarchy will frustrate you. If it sounds like documentation you wish other projects had, the trade is in your favour.

Licence and what it means for reuse

Omarchy is released under the MIT License, per the README. That is a permissive licence: it allows use, modification and redistribution, including in proprietary work, provided the copyright notice and permission notice are preserved. For a desktop distribution this matters less for the operating system itself, which is assembled from many upstream components under their own licences, and more for the parts the project authors: the shell scripts, themes and defaults in this repository.

If you fork Omarchy to build your own branded desktop, the MIT terms on this repository do not extend to the Arch packages, the Hyprland compositor or the bundled applications, each of which carries its own licence. The manual's Branding chapter is the relevant reading if that is your intent. This is a description of the licence text, not legal advice.

Editorial conclusion

Omarchy suits people who want a configured Hyprland desktop on Arch and are willing to accept DHH's defaults, including the bundled applications and the manual's conventions. It does not suit anyone who wants a minimal Arch install they assemble themselves, or a distribution with a conventional GNOME or KDE desktop and a graphical settings panel. Before adopting it, read manual/30-updates.md, manual/31-dotfiles.md and manual/47-system-snapshots.md, because those three pages define how upgrades, personal configuration and rollback are expected to work, and they are the parts that decide how much of the system you own after install.

Frequently asked questions

Official sources

1. License: MIT
2. omacom/omarchy on GitHub
3. Project website
4. README
5. Releases