Guide · Open source
How to use Omarchy: install, learn the basics and configure it
Updated · written with AI from the project's own documentation and checked against our catalogue data
Omarchy is a Linux distribution, meaning a complete operating system, that ships preconfigured with a specific look, a theme system and a set of tools. This guide explains what it is, how to get the source and how to find your way through its manual. After reading, you will know which parts of Omarchy matter for your use and where the official documentation covers each one.
Omarchyomacom/omarchy · ★ 46.1k · MIT Install options & downloads Quick start
- 1Read the project homepage. Visit omarchy.org to read more about the project before you install anything.
- 2Clone the repository. Run the git clone command from the README to download the Omarchy source to your machine.
- 3Open the manual. Go to the manual folder in the repository. Its pages are the authoritative documentation.
- 4Start with Getting Started. Read the Getting Started page and, if you are switching from Mac or Windows, the Coming From Mac or Windows page.
- 5Learn the basics. Read Navigation, The top bar, Themes and Hotkeys to understand the desktop.
- 6Configure and maintain. Use the Configuration pages for changes and the Updates page to keep the system current.
What Omarchy is and who it suits
Omarchy is a full operating system rather than an app you add to an existing system. The README describes it as a beautiful, fun and agentic Linux distribution by DHH, and the project's homepage is omarchy.org.
It is a good fit for Linux users who want a ready-made, opinionated desktop instead of assembling one, and for developers who want a preset terminal, Neovim and shell tooling setup. It is less suited to people who want full control over every package and default, because the distribution makes many choices for you.
- Good fit: people who want a curated base to customize
- Good fit: people coming from Mac or Windows, since the manual has a dedicated guide for that transition
- Poor fit: anyone wanting a lightweight install on an existing system
- Check first: hardware support, since the README does not detail compatibility
Get the Omarchy source and read the manual
The README gives one install command: cloning the repository. The manual lives in the manual/ folder of the repository and is described as its authoritative source, so use it as your main reference.
The manual is organised into three groups: The Basics, The Applications and Configuration, followed by a final group called The Rest.
- Welcome to Omarchy and Getting Started
- Coming From Mac or Windows
- Navigation, the top bar, Themes and Hotkeys
- Terminal, Neovim, AI, Development Tools and Shell Tools
- Updates, Dotfiles, Monitors, Networking and Fonts
- Troubleshooting, FAQ, System snapshots, Security and Dual Boot Install
git clone https://github.com/omacom/omarchyLearn the desktop basics: themes, hotkeys and the top bar
The Basics section covers the everyday parts of the desktop. Start with Navigation and The top bar to understand how the interface is laid out, then read Hotkeys, since keyboard shortcuts are central to working in the environment.
Themes are a core feature. The manual's Themes page explains the theme system, and a later page, Making your own theme, covers creating your own. Read the Themes page before changing the look so you know how the pieces fit together.
- Navigation: how to move around the desktop
- The top bar: status and controls along the top
- Hotkeys: the keyboard shortcuts
- Unified Clipboard & History, Reminders, Notices and Screenshots & Recording
- Toggles, idle & screensaver, and the Omarchy CLI
Use the preset applications and development tools
Omarchy comes with a preset terminal, Neovim configuration, AI tools and shell tooling. The Applications section documents each one, so you can learn what is installed before you change it.
Development Tools, Shell Tools and Shell Functions are the pages to read if you write code on the system. Browsers, GUIs, TUIs and Web Apps cover the rest of the everyday software.
- Terminal and Neovim
- AI and Development Tools
- Shell Tools and Shell Functions
- TUIs and GUIs
- Browsers and Web Apps
- Gaming, Filling out PDFs and Windows VM
Configure and maintain your system
The Configuration section covers the settings you are likely to change: monitors, keyboard, mouse and trackpad, networking, sleep, fonts, backgrounds and the prompt. Dotfiles and Common tweaks show how to adjust the base setup.
Keep the system current through the Updates page, and read System snapshots and Security for maintenance topics. The README does not describe the update process in detail, so follow the manual page for exact steps.
- Updates and System snapshots
- Dotfiles and Shell plugins
- Monitors, Keyboard, Mouse, Trackpad and Networking
- Fonts, Backgrounds and Prompt
- Branding and Common tweaks
What people use it for
- Setting up a ready-made Linux desktop without assembling one yourself
- Moving from Mac or Windows with a dedicated transition guide
- Working with a preset terminal, Neovim and shell tooling
- Customizing themes and configuration on top of a curated base
Frequently asked questions
Is Omarchy free?
Omarchy is released under the MIT License, as stated in the README. The license text is linked from the repository, so you can read the terms there.
What do I need to install Omarchy?
The README lists no prerequisites. The install method is not spelled out beyond cloning the repository, so check the manual for setup steps and hardware notes.
Does Omarchy support my hardware?
The README mentions Mac support and hardware authentication but does not detail compatibility. Check the Mac support and Hardware authentication pages in the manual before you install.
Is Omarchy the same as Arch Linux?
No. Omarchy is itself a Linux distribution with its own preset look and tools. Comparable open-source Linux distributions include Arch Linux, Fedora and Ubuntu, which offer less preconfigured setups.
Can I install Omarchy on an existing system?
Omarchy is a full operating system, not a lightweight add-on. The manual includes a Dual Boot Install page, which is the place to check how it can sit alongside another operating system.
Can I customize Omarchy themes?
Yes. The manual has a Themes page and a Making your own theme page, so you can adjust the look on top of the curated base.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Omarchy suits Linux users who want an opinionated, ready-made desktop with preset terminal, Neovim and shell tooling, and newcomers from Mac or Windows who want a guided transition. Pick a more traditional distribution such as Arch Linux, Fedora or Ubuntu if you want full control over every package and default, or if you need a lightweight install on an existing system.
Install options & downloads