The Omarchy Manual
Table of contents.
Fifty-one chapters covering the complete Omarchy experience. Search by chapter below or press/while reading.
- 01
Welcome to Omarchy!
Omarchy is an omakase Linux distribution based on Arch, the tiling window manager Hyprland, and the desktop construction-kit Quickshell. It ships with everything a modern, savvy computer user needs to be productive immediately. From Neovim (btw) to Chromium, Obsidian to LibreOffice, and Kdenlive to OBS Studio. Hell, even a retro Winamp-style music player is there!
- 02
Getting Started
Omarchy is installed using an ISO. You can choose between a full-disk install, which takes over the entire drive, or a free-space install, which puts Omarchy in the unallocated space on a drive — that's how you dual boot alongside Windows or another OS (see dual-boot install — note that you'll need to turn off BitLocker in Windows first). Either way, the installation defaults to full encryption, and the full-disk option will wipe the selected drive, so be sure to take a backup before using an existing one!
- 03
Coming From Mac or Windows
If you've spent years on macOS or Windows, your fingers know a hundred things your brain has forgotten it ever learned. This chapter is the translation layer: where those instincts go in Omarchy. The features themselves are covered in depth elsewhere — this is just the map.
- 04
Navigation
Everything in Omarchy happens via the keyboard — EVERYTHING! When the system first starts, you literally can't do a thing with the mouse alone. But you can hit Super + Space to reveal the Omarchy Menu and from here you to do just about everything.
- 05
The Top Bar
The strip along the top of your screen is the Omarchy bar. It's not a bolted-on status bar but part of the Omarchy shell, the single long-running Quickshell process that also draws the menu, the notifications, the OSD popups, and the lock screen. That's why it themes perfectly with everything else and why a panel opens instantly instead of spawning a new app.
- 06
Themes
Omarchy comes with twenty-two beautiful themes. You can select between them via Style > Theme in the Omarchy Menu (Super + Space) or hop directly to the theme selector using Super + Ctrl + Shift + Space.
- 07
Hotkeys
You can see all the main keyboard bindings with Super + K (Tmux bindings with Super + Alt + K and Herdr bindings with Super + Ctrl + K).
- 08
Unified Clipboard & History
Usually on Linux, you need Ctrl + Shift + C/V to copy'n'paste in the terminal and Ctrl + C/V to do it everywhere else. That's hard to get used to for anyone who hasn't been born and bred on Linux! So too is the switch from super to ctrl, if you're coming from the Mac.
- 09
Reminders
Omarchy has a built-in way to set simple reminders based on a countdown timer and with a message. You can do this via Super + Ctrl + R, seeing all the ones set via Super + Ctrl + Alt + R, and clearing all via Super + Ctrl + Shift + R. Everything also accessible via Trigger > Reminder. You can also use the cli with omarchy reminder 7 'Tea ready'.
- 10
Notices
You can quickly access the date and time, battery status, and current weather using the hotkey notices.
- 11
Text Extraction & Dictation
Hit Super + Ctrl + PrtScr to select a region on the screen for text extraction. The tesseract open source OCR model will then quickly convert that selection into text and place it on the clipboard. Then you just hit Super + V to paste.
- 12
Screenshots & Recording
Everything you can grab off the screen hangs off the Print Screen key. One key on its own takes a picture, and the modifiers take a recording, a colour, or the text inside a region. If your keyboard doesn't have a Print Screen key at all, Super + Ctrl + C opens the same set as a menu.
- 13
Toggles, Idle & the Screensaver
A lot of what you change day to day isn't really a setting. It's a mode you flip on for an hour and off again: night light while you're working late, do not disturb while you're presenting, stay awake while you're watching something. Omarchy calls those toggles, and they all work the same way — a hotkey, a menu entry, and a command, all hitting the same switch.
- 14
Omarchy CLI
Omarchy is usually controlled through the hotkeys and the Omarchy menu (Super + Space). But you can also control it through the omarchy CLI. This is particularly helpful when you're having an AI agent work with you on customization or configuration.
- 15
Terminal
Foot is the default terminal for Omarchy. It's fast, lightweight, and compatible with even old computers. It does not, however, support native tabs or splits.
- 16
Neovim
Neovim is a modern implementation of the vi editor>) created by Bill Joy all the way back in 1976. It's a modal editor where insert mode and command mode are separated, and it's a bit of a superpower once you learn even just a subset of the incredibly deep key command set. But it's also quite the learning curve!
- 17
AI
Omarchy treats AI coding agents as first-class citizens, but it doesn't pick a favorite for you. Instead, every major coding-agent CLI comes pre-wired as a lazy-loaded launcher. The launchers are tiny mise-managed stubs in ~/.local/bin/, so nothing is downloaded until the first time you actually run one. Invoke any of these and authenticate when prompted:
- 18
Development Tools
Omarchy ships with Neovim by default, but if you'd like something a bit more mainstream and familiar, you can run the Omarchy Menu (Super + Space) and see the options under Install > Editor. We have VSCode, Cursor, Zed, Sublime Text, Helix, Vim, and Emacs listed there. If you don't find what you're looking for, checkout Install > Package, and see if it isn't in an Arch package (and if not, try Install > AUR to check the AUR).
- 19
Shell Tools
In addition to the standard Linux tools, Omarchy also ships with a bunch of enhanced shell tools. Here are the key ones.
- 20
Shell Functions
Omarchy comes with a set of shell functions to simplify common tasks and encapsulate convoluted parameter calls.
- 21
TUIs
Lazygit is a delightful alternative to something like the GitHub Desktop application, and it runs inside the terminal.
- 22
GUIs
Files (Nautilus) is the graphical file manager. Super + Shift + F opens it, and Super + Shift + Alt + F opens it in the directory your terminal is sitting in, which saves a lot of clicking. Ctrl + L lets you type a path, and hitting Space on any file gives you a quick preview without opening anything.
- 23
Browsers
Omarchy ships with Chromium as the default browser. It's the plain open-source build, themed to match the rest of your system, and it's what Super + Shift + Return opens and what every web app runs inside.
- 24
Commercial apps/services
Omarchy is mostly focused on providing free, open source software, but it's not religious about it. Sometimes the best solution is a commercial offering, and that's just fine. Here are some of the options we provide an easy installation for.
- 25
Web Apps
You can add your own web apps using Install > Web App in the Omarchy menu (Super + Space). It'll ask you for the app name, app URL, and the icon URL, if it can't retrieve it via favicon. You can get great PNG icons for many popular web apps on Dashboard Icons.
- 26
Gaming
Omarchy isn't just for pRoDUcTiVItY, it's also for having fun, and what's more fun than gaming? Omarchy ships with a whole suite of gaming options — Steam and RetroArch for native and retro play, Battle.net, Lutris, and Heroic for non-Steam stores, Moonlight for PC streaming, Xbox Cloud Gaming + NVIDIA GeForce NOW for cloud, plus the evergreen Minecraft.
- 27
Filling out PDFs
Omarchy ships with a nice, basic PDF viewer called Document Viewer. This is the program that'll open any PDFs you just double click on.
- 28
Windows VM
Omarchy offers an easy way to run Windows through a Docker VM. You can install it using Install > Windows from the Omarchy menu (Super + Space).
- 29
Other Packages
Arch has an amazing wealth of packages available for almost any type of software between the official repository and the Arch User Repository (AUR).
- 30
Updates
Omarchy and your packages are kept up to date via Update > Omarchy in the Omarchy menu (Super + Space).
- 31
Dotfiles
Omarchy is primarily configured through the so-called dotfiles that live in ~/.config. Those are considered your files for your changes. The files that live in /usr/share/omarchy belong to Omarchy itself, and you shouldn't be messing with those. If you need to change anything in /usr/share/omarchy, you should be overwriting the value in ~/.config instead.
- 32
Shell Plugins
The Omarchy desktop runs as a single long-lived Quickshell process called omarchy-shell, and almost everything you see on screen is a plugin inside it. The bar is a plugin. So are the panels that drop down from it, the fullscreen overlays like the emoji picker and the clipboard manager, the Omarchy menu itself, the lock screen, the polkit dialog, and the headless services that watch your battery and warm your screen up at night.
- 33
Monitors
Omarchy assumes you're running on a 2x-capable retina-class display by default. This is what you need to get those nice, crisp programmer fonts. It's what almost all new premium laptops with high-resolution screens are optimized for. It's what you'd want to run on a 27" 5K Apple Studio Display/ProArt PA27JCV/Samsung S9/Kuycon G27P or 32" 6K Apple XDR/ProArt PA32QCV/Kuycon G32P.
- 34
Keyboard, Mouse, Trackpad
Hyprland lets you configure all your inputs in great detail. You can change the keyboard repeat to be supersonically fast or make the trackpad use natural scrolling. You change all of it in ~/.config/hypr/input.lua, which you can also reach via Setup > Input in the Omarchy menu (Super + Space). Anything you set there replaces Omarchy's defaults.
- 35
Networking
Networking in Omarchy is handled by NetworkManager, and you drive it from the network icon in the top bar or with Super + Ctrl + W.
- 36
System sleep
Omarchy enables suspend and hibernation by default, but if you're having issues with either on your machine, you can toggle them off.
- 37
Hardware authentication
A lot of laptops come with a fingerprint sensor to do authentication. You can use this with Omarchy by running Setup > Security > Fingerprint in the Omarchy menu (Super + Space).
- 38
Fonts
Omarchy uses JetBrainsMono Nerd Font as both the terminal and system font by default.
- 39
Backgrounds
Every theme ships with its own set of backgrounds, and you can add extras of your own in ~/.config/omarchy/backgrounds/[theme]. If you want to add an extra background image to, say, the nord theme, you just put the file in ~/.config/omarchy/backgrounds/nord.
- 40
Prompt
Omarchy ships with a minimal Starship prompt by default. That's how I like to keep my prompt. I don't need to know the user, because it's always me, and I don't need to know the time, because it's always at the top.
- 41
Branding
Omarchy allows you to set your company logo or personal image for both the boot unlock, the screensaver, and the about screen.
- 42
Common tweaks
This is a collection of common tailorings to the Omarchy setup. Know that it might occasionally be necessary for system updates to restore certain configs to their original condition. If this happens, your changes won't be lost, but put in a .bak file in the same directory.
- 43
Making your own theme
You can add your own themes to ~/.config/omarchy/themes. Just copy one of the existing ones as a base (look in /usr/share/omarchy/themes), then tweak to your delight. As long as your theme is inside that folder, it'll be included in the theme selection menu.
- 44
Mac support
Omarchy has built-in support for Intel Macs. There are a couple of known limitations at the moment, but as long as you're aware and OK with those; you can breathe some new life into your old Macs by loading Omarchy.
- 45
Troubleshooting
First try to rollback your system the version before your recent update. If that doesn't work, use omarchy-debug to share with your problem on #omarchy-help in the Discord. And if all that fails, you can reinstall the defaults configs and packages using omarchy-reinstall.
- 46
FAQ
Edit your ~/.config/hypr/input.lua file and add this to switch between layouts on Left Alt + Right Alt:
- 47
System snapshots
We create snapshots automatically on every Omarchy update, but should you want to create your own, you can use omarchy-snapshot create.
- 48
Security
Omarchy takes security extremely seriously. This is meant to be an operating system that you can use to do Real Work in the Real World. Where losing a laptop can't lead to a security emergency. So here's what we do:
- 49
Omarchy on...
Asahi Alarm is a version of Arch for Apple M1/M2 computers built on top of Asahi Linux. You can get Omarchy running on top of that with some effort. See the user-driven guide.
- 50
Dual Boot Install
You're able to install Omarchy to a single partition alongside Windows or other installations.
- 51
Unattended Installs
The Omarchy ISO can install itself with nobody at the keyboard. If the installer finds a second drive labeled cidata carrying its configuration files, it copies them off, skips the setup wizard entirely, and reboots into the finished system on its own. No special ISO build, no extra boot menu entry — with no such drive attached, nothing changes and you get the normal wizard.
No chapters match that search.