Omarchy: An Opinionated Arch-Based Desktop, Assembled Through Shell Scripts
Beautiful, Modern & Opinionated Linux
At a glance
- What is it?
- Omarchy is a Shell-based Linux distribution by DHH that ships a curated set of defaults on top of Arch, with a 51-chapter manual as its authoritative documentation. The interesting question is not whether it looks good but whether you want someone else's defaults baked into your install.
- Who is it for?
- Adopt Omarchy if you want an Arch-derived desktop where the choices are already made and you are willing to work inside its manual rather than against it. Do not adopt it if you need a distribution with a formal security response process, long-term release branches, or a support contract.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Omarchy Is Actually Selling
The repository describes Omarchy as "a beautiful, fun & agentic Linux distribution by DHH." That sentence is the whole pitch, and it tells you the target audience precisely. This is not a distribution for someone who wants to assemble a desktop from parts. It is for someone who has already decided they want a tiling-window, keyboard-driven environment and does not want to spend a weekend choosing a bar, a launcher, a terminal, a prompt and a theme palette.
The problem it solves is configuration drift. A stock Arch install gives you a package manager and a wiki. Everything above that is your problem, and the result is that two Arch machines belonging to the same person rarely look or behave alike. Omarchy's answer is to make the decisions once, in Shell, and ship them as the distribution. The manual's table of contents is the evidence: separate chapters for the top bar, hotkeys, themes, clipboard history, screenshots, idle and screensaver behaviour, monitors, keyboard and trackpad, fonts, backgrounds and prompt. Each of those is a decision someone already made for you.
The primary language being Shell matters more than it first appears. It means the distribution's behaviour is inspectable. There is no compiled configuration daemon hiding the logic. If you want to know what a hotkey does, the answer is a script you can read. That is a real advantage over distributions that wrap their defaults in binaries, and it is also why the project's update story has to be handled carefully, which I will come back to.
The Manual Is the Product, Not the README
The README is a table of contents and almost nothing else. It states plainly that the manual lives in manual/ and that this directory is "its authoritative source," mirrored to learn.omacom.io where the screenshots are hosted. That is an unusual arrangement and worth taking at face value: the README will not tell you how to install, and you should not expect it to.
The manual is organised into four groups. The Basics covers getting started, navigation, the top bar, themes, hotkeys, clipboard history, reminders, notices, text extraction and dictation, screenshots and recording, toggles and idle behaviour, and the Omarchy CLI. The Applications group covers terminal, Neovim, AI, development tools, shell tools, shell functions, TUIs, GUIs, browsers, commercial apps, web apps, gaming, PDF filling, a Windows VM and other packages. Configuration covers updates, dotfiles, shell plugins, monitors, input devices, networking, system sleep, hardware authentication, fonts, backgrounds, prompt, branding, common tweaks and making your own theme. The Rest covers Mac support, troubleshooting, FAQ, system snapshots, security, running Omarchy on other things, dual boot install and unattended installs.
Two chapters in that list are the ones I would read first, and neither is the welcome chapter. The dotfiles chapter determines how much of your existing setup survives contact with the distribution. The updates chapter determines what happens on the next release. A distribution that owns your configuration has to answer both questions convincingly, and the manual structure suggests the project knows this.
The presence of a dedicated security chapter and a dedicated troubleshooting chapter is a good sign about intent. It is not evidence about content. I have not read those chapters in full, and the README does not summarise them, so treat the existence of the chapters as a pointer rather than a guarantee.
Release Cadence and the Shell Update Problem
The repository shows three releases in roughly two weeks: v4.0.1 on 2026-08-25, v4.0.2 on 2026-08-31, and v4.0.3 on 2026-09-08. The default branch is named quattro, which is consistent with a v4 line. The last push recorded is 2026-09-10, two days after v4.0.3.
That cadence is the single most important operational fact about this project. Patch releases landing weekly on a distribution that manages your dotfiles and your shell environment means configuration files will be touched regularly. Anyone evaluating Omarchy should read manual/30-updates.md before installing, because the manual has a dedicated chapter for it and the README gives no summary of what an update actually does to your home directory.
There is a second question the README does not answer: what happens when an update changes a file you have edited. Shell-based configuration systems typically solve this with one of three approaches, namely overwriting, backing up, or refusing to proceed on a modified file. Which one Omarchy uses is not stated in the README. This is the first thing I would verify by reading the updates and dotfiles chapters together, because the answer determines whether you can safely customise anything.
The presence of manual/47-system-snapshots.md is relevant here. A snapshot mechanism implies the project expects updates to sometimes go wrong and expects users to roll back. That is a reasonable posture for a rolling distribution, but it also means the recovery path is part of the normal workflow rather than an emergency measure.
Theming as a First-Class Feature, and Its Cost
Themes get their own chapter, and so does making your own theme. Branding gets a chapter too. Backgrounds, fonts and prompt each get one. That distribution of attention is deliberate: the visual layer is treated as a supported part of the system rather than decoration you bolt on afterwards.
The practical consequence is that Omarchy likely expects themes to be applied through whatever mechanism the theme chapter documents, rather than by editing individual application configs. If you apply a theme that way, the update path stays clean. If you instead hand-edit your terminal colours, your bar colours and your editor colours separately, you have created three files that updates may or may not respect, and you have opted out of the theming system while still being subject to its updates.
The cost of a first-class theming layer is that it constrains how applications are configured. A theme system has to reach into every application it covers, which means those applications are configured the way the theme system expects. Adding an application that the theme system does not know about is possible, but it will not participate in theme switching, and it may look out of place after the next theme change.
This is the central trade-off of the whole distribution. You get coherence, and you pay for it with a narrower set of supported ways to configure things. Whether that is a good deal depends entirely on how much you enjoy configuring things, which is a question only you can answer.
What the Manual Chapters Imply About the Default Stack
You can infer a fair amount from chapter titles without reading them, and it is worth being explicit about what is inference rather than documentation.
The Applications group lists terminal, Neovim, TUIs and GUIs as separate chapters. That suggests a terminal-first workflow with a curated set of text-mode tools and a smaller set of graphical ones, documented separately. The presence of a dedicated AI chapter, combined with the README's word "agentic," indicates that AI tooling is treated as part of the base system rather than something you install yourself. The Windows VM chapter and the gaming chapter indicate that the distribution is not positioned as a work-only environment.
The Basics group lists clipboard history, reminders, notices, text extraction and dictation, screenshots and recording, and toggles with idle and screensaver behaviour. Those are desktop conveniences that most distributions leave to individual applications. Documenting them centrally means Omarchy has opinions about how they work and probably wires them together, for example a screenshot tool that feeds the clipboard history.
What I cannot tell from the README is which specific applications back each of those chapters. The README names no packages. Anyone deciding whether to adopt this should read manual/15-terminal.md, manual/16-neovim.md and manual/17-ai.md before committing, because those three chapters determine most of your daily experience and the README gives you nothing about them.
Getting It Running, and What the README Does Not Tell You
Here is the honest answer about installation: the README does not document it. It links to manual/02-getting-started.md and manual/50-dual-boot-install.md and manual/51-unattended-installs.md, and that is the extent of what the README provides. I am not going to invent a boot command or an ISO URL.
What the README does give you is the documentation map, and that map is specific enough to act on. If you are installing alongside an existing operating system, manual/50-dual-boot-install.md is the relevant chapter. If you are provisioning machines in bulk, manual/51-unattended-installs.md is the one that matters, and the fact that it exists at all suggests the project is used in contexts beyond a single personal laptop.
For post-install configuration, the chapters you will actually open are manual/31-dotfiles.md, manual/32-shell-plugins.md, manual/42-common-tweaks.md and manual/43-making-your-own-theme.md. The manual also has a chapter on the Omarchy CLI at manual/14-omarchy-cli.md, which is presumably the supported way to drive system-level actions such as updates and theme changes. Given that the distribution is written in Shell, that CLI is likely a thin wrapper over scripts you can read directly, but the README does not confirm this.
The gap I would flag to anyone evaluating this project is that the README provides no prerequisites, no supported hardware list, and no statement about which Arch base it tracks. Those are ordinary things to want before installing an operating system, and you will have to find them in the manual.
Where Omarchy Is the Wrong Choice
An opinionated distribution is a bad fit whenever your requirements conflict with its opinions, and the conflict is usually not negotiable. If you need a specific desktop environment that Omarchy does not use, or a specific window manager, you are fighting the distribution rather than using it. The manual documents how to make your own theme, not how to replace the compositor.
A second and more serious limitation is support. The README states the licence is MIT and points to the Open Source Initiative's page for it. MIT is permissive: it grants you the right to use, modify and redistribute the code, and it comes with no warranty. There is no support contract, no service-level agreement, and no security response commitment documented in the README. The manual has a security chapter, but a chapter is documentation, not a process. If you are deploying this in an environment where you need a vendor to answer for a vulnerability, Omarchy is not that vendor, and no amount of reading the security chapter changes that.
A third limitation is the rolling model itself. Weekly patch releases on a system that manages your dotfiles means change is continuous. If your workflow cannot tolerate a configuration file moving underneath you on a Tuesday, this is the wrong distribution regardless of how good the defaults are.
Finally, the MIT licence permits redistribution, including modified redistribution. That is a normal property of permissive licensing and it means forks are allowed. It is not a defect, but it does mean that if you encounter Omarchy in the wild, you should check whether it is the upstream project or a derivative before assuming the manual applies. This is a description of the licence terms, not legal advice; if licensing matters to your organisation, have someone qualified read it.
The Alternative, and the Actual Difference
The obvious comparison is plain Arch Linux with a desktop environment you install yourself, or a distribution like Fedora Workstation that ships a complete desktop out of the box. The difference in approach is where the decisions live.
With plain Arch, the decisions live in your head and in your dotfiles repository. You choose the compositor, the bar, the launcher, the terminal, the prompt and the theme, and you maintain the glue between them. The benefit is that nothing changes unless you change it. The cost is that you are the maintainer of a small distribution, and the work is ongoing rather than one-time.
With Fedora Workstation, the decisions live with a large vendor that ships a fixed desktop environment on a predictable release schedule with a formal security process. You get stability and accountability, and you give up the ability to change the desktop's fundamental structure without stepping outside the supported configuration.
Omarchy sits between those two. It makes the decisions for you, like Fedora, but it makes them in Shell on top of a rolling base, like Arch. The distinguishing property is inspectability. Because the distribution is Shell, the decisions are readable scripts rather than opaque defaults. That is the actual argument for choosing it over a conventional opinionated distribution, and it is a stronger argument than the aesthetics.
The corresponding weakness is that Shell is a language without a package manager's guarantees. A configuration system written in Shell can do anything to your home directory, and the only protection is whatever the update mechanism implements. That is why the updates and dotfiles chapters are the ones that determine whether this distribution is trustworthy for your use, not the themes chapter.
Editorial conclusion
Adopt Omarchy if you want an Arch-derived desktop where the choices are already made and you are willing to work inside its manual rather than against it. Do not adopt it if you need a distribution with a formal security response process, long-term release branches, or a support contract. Before installing, read manual/31-dotfiles.md to see how your existing configuration would be overwritten, manual/30-updates.md to understand the update path, and manual/47-system-snapshots.md to confirm a rollback exists for your hardware.
Community notes