Move Welcome to Omarchy
Open Welcome to Omarchy
Welcome to Omarchy!
Omarchy is an omakase remix of Arch Linux using the tiling window manager Hyprland. It ships with just about everything a modern software developer needs to be productive immediately. That's everything from Neovim (btw) to Spotify, Chromium to Typora, and Alacritty to LibreOffice. Hell, even Zoom is there!
This isn't just a grab bag of preinstalled packages, though. It's a complete system designed with both aesthetics and productivity in mind. Because a beautiful system is a motivating system, and productivity has always been downstream from motivation.
It's true that developing an eye for the beauty of a TUI-heavy, theme-delighted, tiling-window-managed system like Omarchy can be an acquired taste. But that's why you're here, isn't it? To e
Welcome to Omarchy
198 words
Move Getting Started
Open Getting Started
Getting Started
Omarchy runs on Arch Linux, so you must install that first. This will wipe everything on the drive you're going to use, so ensure you have a backup! There isn't any dual-boot option either (since that's incompatible with disk encryption). This is a clean-sweep install process.
- Download the Arch Linux ISO, put it on a USB stick (use balenaEtcher on Mac/Windows), and boot off the stick (remember to turn off Secure Boot in the BIOS!).
- If you're on wifi, start by running
iwctl
, then type station wlan0 scan
, then station wlan0 connect <tab>
, pick your network, and enter the password. If you're on ethernet, you don't need this.
- Run
archinstall
and pick these options (and leave anything not mentioned as-is):
Section |
Option |
Mirrors and repositories |
Select regions > Your country |
Disk configuration |
Partitioning > Default partitioning layout > Select disk ( |
Getting Started
598 words
Move Navigation
Open Navigation
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 Walker application launcher and Super + Alt + Space
to open the main Omarchy menu. These two commands allow you to do just about everything.
But Walker is not intended to be the main way to operate the system most of the time. We can get faster than that! All the most important applications are bound directly to individual hotkeys. You start a browser with Super + B
and the terminal with Super + Return
. Try doing one after the other, and you'll see the magic of Hyprland's tiling in action:
You can then hit Super + J
to stack them horizontally instead of vertically:
Hit Super + J
again to return them to horizontal positions. Then try `S
Navigation
349 words
Move Themes
Open Themes
Themes
Omarchy comes with eleven beautiful themes. You can select between them using Super + Ctrl + Shift + Space
(or under Style > Theme with the Omarchy menu on just Super + Alt + Space
). Each theme styles the desktop, terminal, neovim, btop, notifications (mako), top bar (waybar), application launcher (walker), and the lock screen (hyprlock).
Tokyo Night
Catppuccin
Everforest
Gruvbox
Osaka Jade
Kanagawa
Nord
Matte Black
Ristretto
Rose Pine
, and Zoxide will take you directly there.
ripgrep
ripgrep searches the contents of files by using rg <pattern> <path>
, like rg Controller app/
to find all mentions of Controller
in the directory app.
This tool is also used by Ne
Shell Tools
272 words
Move Shell Functions
Open Shell Functions
Shell Functions
Omarchy comes with a set of shell functions to simplify common tasks and encapsulate convoluted parameter calls.
compress [file.tar.gz]
/ decompress [file.tar.gz]
: Create or expand a tar.gz file.
iso2sd [image.iso] [/path/to/sdcard]
: Create a bootable drive on an SD card using the referenced iso file.
format-disk [/dev/drive]
: Format an entire disk with a single ext4 partition. Be careful!
Shell Functions
63 words
Move TUIs
Open TUIs
TUIs
Lazygit
Lazygit is a delightful alternative to something like the GitHub Desktop application, and it runs inside the terminal.
You can run it directly, by going to any directory managed by git and running lazygit
. Or you can run it inside Neovim where it can be started with Space G G
.
You hop between the different panes using Tab
. In the Files pane, you select files for staging using Space
, and then you can create a new commit using c
. You can see all the commands available using ?
.
Lazydocker
Lazydocker is made in the same spirit like Lazygit, and also gives you a terminal interface for managing your containers and images.
You can start it with Super + D
.
You stop a container using s
or start/restart it using r
. See all commands using ?
.
Btop
Btop is a beautiful resource manager that shows memory, CPU, disk, and
TUIs
293 words
Move GUIs
Open GUIs
GUIs
Obsidian
Obsidian is a free and highly extensible note taking application that uses simple Markdown files for storage.
It offers a commercial add-on for syncing with mobile apps on iOS and Android, but if you don't need that, it's free for personal use (and $50/year for commercial use).
You start Obsidian with Super + O
.
Pinta
Pinta is a basic image editing tool that's great for cropping, resizing, and other basic manipulations. Just don't expect a Photoshop alternative. But it's still got a Magic Wand and layers!
You start Pinta via the application launcher (Super + Space
).
LocalSend
LocalSend lets you send files to other devices on the same network running the app, like Apple's AirDrop. It's cross-platform, though, so you can send files to and from Windows, macOS, Android, iOS, and of course Linux.
LibreOffice
[
GUIs
342 words
Move Commercial GUIs
Open Commercial GUIs
Commercial GUIs
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.
1Password
Keeping your passwords in a password manager is a best practice. Doubly so if you're working with a team. And 1password is a great solution, which also comes with a command line tool for integrating key lookups in scripts.
You start 1Password with Super + /
.
Typora
Typora is a minimal, distraction-free writing tool in the same spirit as iA Writer for the Mac and Windows. Like Obsidian, it uses Markdown for formatting, but in a way that's focused on writing individual pieces or essays and very little else.
Best used in full screen mode (F11) for that totally immersive nothing-but-words look.
It comes with a 15-day free trial, and is then a $15 one-time cost.
You s
Commercial GUIs
271 words
Move Development Tools
Open Development Tools
Development Tools
Installing your editor
Omarchy ships with Neovim by default, and uses the LazyVim distro. It's an awesome terminal-based editor built on the proud legacy of Vi, which stretches all the way back to the 70s. It's a delightful, but acquired taste. It's the only editor that's tied into the theme switcher by default.
If you'd like something a bit more mainstream and familiar, here's how to get it:
Editor |
Install |
VSCode |
yay -S vscodium-electron-bin |
Cursor |
yay -S cursor-bin |
Zed |
yay -S zed |
Emacs |
yay -S emacs |
Mise
Mise lets you install and run multiple versions of a programming language on the same machine. It's like rbenv or rvm for Ruby or virtualenv for Python, but it works for a bunch of different environments.
To install, say, Ruby 3.3, you'd run mise use -g ruby@3.3
, which will both install Ruby 3.3 and set it as the global defa
Development Tools
415 words
Move Filling out PDFs
Open Filling out PDFs
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.
But you can only use Document Viewer to fill out PDFs that have been setup as forms. If you need to fill out PDFs that haven't, or you need to sign a PDF, you'll have to right-click the file, select Open With..., and pick Xournal++.
Xournal++ will let you write anywhere on a PDF using the T tool. If you need to sign a document, you'll need an image of your signature, and you can use the Image tool to insert this signature and resize it.
When you're done filling out the PDF, use File > Export as PDF to save the final version.
Filling out PDFs
132 words
Move Web Apps
Open Web Apps
Web Apps
These web apps live in ~/.local/share/applications
. They're just .desktop
text files. You can make your own or remove the default ones by cloning or deleting these files.
It's best if you log into all your accounts using a regular browser before using the web app shortcuts. The thin wrapper frame doesn't work well with 1password, so just easier to be logged in directly first.
All the keyboard hotkeys for these web apps can be changed in ~/.config/hypr/bindings.conf
.
HEY
HEY is an email and calendar service that serves as a great alternative to people tired of Gmail, Outlook, or Apple Mail. It's made by 37signals where Omarchy originated.
You can start HEY Email using Super + E
and HEY Calendar using Super + C
.
Basecamp
Basecamp is a project management service that helps small teams move faster and make more progress. Instead of patching together a mishmash of Trello, Slack, Asana, Noti
Web Apps
361 words
Move Gaming
Open Gaming
Gaming
Omarchy isn't just for pRoDUcTiVItY, it's also for having fun, and what's more fun than gaming? Two of the best options for playing games on Omarchy are Steam (modern games) and Retroarch (retro games).
Thanks to Valve's incredible work on the proton compatibility layer, there are now tens of thousands of playable modern games on Linux. Oh, and did you know that the Steam Deck actually runs Arch!
Steam
Install Steam by selecting Install > Steam from the Omarchy menu (Super + Alt + Space
).
(Make sure you pick the packages made for your GPU! If you're on an AMD with an iGPU, just pick the first package. Otherwise there are options for Nvidia and Radeon.)
After you've installed it, you'll be able to launch Steam with Super + Space
and typing steam
.
Note that Steam can take 10-20 seconds to start up, and it's not going to provide any
Gaming
259 words
Move Other Packages
Open Other Packages
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).
It couldn't be easier to use either. You install a new package by going to Install > Package in the Omarchy menu (Super + Alt + Space
) and typing the package you want. It'll automatically fuzzy filter the list of all packages. (You can also do it manually using with yay -S [package]
in the terminal).
If you want to remove a package, you can use Remove > Package from the Omarchy menu. It'll remove package, config files, and dependencies. (You can also do it manually using yay -Rns [package]
).
Here are some common packages you might like:
Program |
Description |
Package |
VSCode |
Microsoft's popular editor |
visual-studio-code-bin |
Cursor |
AI-powered editor |
cursor-bin |
Claude Code |
AI-assist in the terminal |
claude-code |
Ghostty [Beta] |
Lovely new |
|
Other Packages
187 words
Move Dotfiles
Open Dotfiles
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 ~/.local/share/omarchy
belong to Omarchy itself, and you ideally shouldn't be messing with those. If you need to change anything in ~/.local/share/omarchy
, you should be overwriting the value in ~/.config
instead.
Almost everything can be edited through Setup > Configs > [process] through the Omarchy menu (Super + Alt + Space
). When you do it this way, any process that needs restarting after config edits automatically will be after you quit the Neovim editor (:wq
, remember!).
Here's a list of the key files in ~/.config
and what they control:
Dotfiles
488 words
Move Fonts
Open Fonts
Fonts
Omarchy uses Caskaydia Mono Nerd Font as both the terminal and system font by default.
You can change this for the terminal through the Style > Font menu in the Omarchy menu (Super + Alt + Space
) or manually by editing ~/.config/alacritty/alacritty.toml
.
You can install other popular programming fonts via Install > Package in the Omarchy menu. Here are some popular font packages:
Font |
Install |
JetBrains Mono Nerd |
ttf-jetbrains-mono-nerd |
Meslo LG Mono Nerd |
ttf-meslo-nerd |
Fira Code Nerd |
ttf-firacode-nerd |
Victor Mono |
ttf-victor-mono-nerd |
Bistream Vera Mono |
ttf-bitstream-vera-mono-nerd |
Fonts
111 words
Move Monitors
Open Monitors
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 laptops like the Framework 13 with it's 2.8K monitor is 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.
So if you're not running a display with a PPI of 218 or above, you'll want to change the monitor settings. For example, if you have a 27" or 32" 4K, you can u
Monitors
268 words
Move Keyboard, Mouse, Trackpad
Open Keyboard, Mouse, Trackpad
Keyboard, Mouse, Trackpad
Hyprland let's 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.conf
, which you can also reach via Setup > Input in the Omarchy menu (Super + Alt + Space
).
Here's an example:
input {
# Use multiple keyboard layouts and switch between them with Alt + Space
kb_layout = us,dk
kb_options = compose:caps,grp:alt_space_toggle
# Change speed of keyboard repeat
repeat_rate = 40
repeat_delay = 600
# Increase sensitity for mouse/trackpack (default: 0)
sensitivity = 0.35
touchpad {
# Use natural (inverse) scrolling
natural_scroll = true
# Use two-finger clicks for right-click instead of lower-right corner
clickfinger_behavior = true
# Control the speed of your scrolling
scroll_factor = 0.3
}
}
# Scroll faster in the terminal
windowrule = scrolltouchpad
Keyboard, Mouse, Trackpad
204 words
Move Fingerprint & Fido2 authentication
Open Fingerprint & Fido2 authentication
Fingerprint authentication
A lot of laptops, like my beloved Framework 13, come with a fingerprint sensor to do authentication. You can use this with Omarchy by running Setup > Fingerprint in the Omarchy menu (Super + Alt + Space
). That'll install the fingerprint package, collect your print, verify it, and you'll be set to go using your fingerprint to unlock from the lock screen (which you can trigger with Super + Escape
), enter sudo mode, and authorize system prompts.
If you've setup fingerprint authentication, but then need to work on an external keyboard that doesn't have it, just hit CTRL + C
, when you're prompted for your fingerprint during sudo
.
You can remove the fingerprint authentication under Remove > Fingerprint in the Omarchy menu.
Both adding and removing fingerprint authentication is also available through the Omarchy TUI under the Setup menu.
Fido2 authentication
If you're using a Fido2 device, you can set it up for sudo
authent
Fingerprint & Fido2 authentication
195 words
Move Backgrounds
Open Backgrounds
Backgrounds
All the backgrounds for Omarchy live in ~/.config/omarchy/[theme]/backgrounds
. If you want to add an extra background image to, say, the nord theme, you just put the file in ~/.config/omarchy/nord/backgrounds
. Then when you're on the nord theme, it'll be included in the cycle of backgrounds you can move between using Super + Ctrl + Space
.
You can open this folder in the file manager using Install > Background in the Omarchy menu (Super + Alt + Space
). Then you can just drag over your image from wherever it is. After you've dragged it in, you can jump to it using that Super + Ctrl + Space
hotkey (or Style > Background in the Omarchy menu).
You can find a huge collection of cool curated backgrounds on https://github.com/dharmx/walls.
Backgrounds
128 words
Move Updates
Open Updates
Updates
Omarchy is intended as a starting point for you to build your own ideal environment, so many of the config files are generated directly, and you're invited to tweak them. But there are also pointers into Omarchy's defaults that you can update from time to time to get the latest through Update > Omarchy in the Omarchy menu (Super + Alt + Space
).
This basically just pulls the latest from the git checkout of Omarchy that lives in ~/.local/share/omarchy
, but if there are major updates in the future, it'll also do a migration from where you are to the latest. And finally, it'll update all system packages using yay -Syu
(which you can also just run on its own).
When new releases are made, a circle arrow icon will appear to the right of your clock. Click it and the update process will start.
Updates
146 words
Move Extra themes
Open Extra themes
Extra themes
You can install any of these themes by copying the GitHub URL and selecting Install > Style > Theme
via the Omarchy menu (Super + Alt + Space
). If you want to remove it again, just use Remove > Style > Theme
and select it there.
Ash
Aura
All Hallow's Eve
Blue Ridge Dark
Dracula
[Green Hakka
Extra themes
111 words
Move Making your own theme
Open Making your own theme
Making your own theme
You can add your own themes to ~/.config/omarchy/themes
. Just copy one of the existing ones as a base, then tweak to your delight. As long as your theme is inside that folder, it'll be included in the theme selection menu.
If you're making a light mode theme, drop an empty file called light.mode
in the root of your theme. Then it'll automatically be paired with light mode for all the apps.
If you'd like to color-match the file manager icons to your theme, add a file called icons.theme
with the name of the icon set you want to you. By default, the options are: Yaru Yaru-blue Yaru-dark Yaru-magenta Yaru-olive Yaru-prussiangreen Yaru-purple Yaru-red Yaru-sage Yaru-wartybrown Yaru-yellow
.
If you want to distribute your theme so others can use it, you need to put it on a public git server, like GitHub. Then people can install it using Install > Theme in the Omarchy menu using that URL. It's recommended that you follow the naming convention of `omarchy-[themename]-theme
Making your own theme
204 words
Move Troubleshooting
Open Troubleshooting
Troubleshooting
Why are some apps so large on my display?
Omarchy assumes a 2x high-resolution display, which requires setting GDK_SCALE
to 2 in ~/.config/hypr/hyprland.conf
. But if you're on a 1x display, you can change this to 1 (and then reset Hyprland with Super + Escape
, then Relaunch). See the manual on monitors.
Why isn't Caps Lock working?
In Omarchy, Caps Lock has been designated to be the xcompose key. That's how you get quick emojis and other autocompletions done. If you really miss using Caps Lock, you can remape the xcompose key to something else by editing ~/.config/hypr/input.conf
, like setting it to the right alt key:
kb_options = compose:ralt
Why are my external speakers not playing?
Probably because they're not set as the primary outpu
Troubleshooting
344 words
Move FAQ
Open FAQ
FAQ
How do I switch between keyboard layouts?
Edit your ~/.config/hypr/input.conf
file and add this to switch between layouts on Left Alt + Right Alt
:
# Use multiple keyboard layouts and switch between them with Left Alt + Right Alt
input {
kb_layout = us,fr
kb_options = compose:caps,grp:alts_toggle
}
You can even configure Waybar to showing your current keyboard layout in the top bar.
How do I change the default terminal to Ghostty (or Kitty)?
First install Ghostty with yay -S ghostty
, then edit ~/.config/hypr/bindings.conf
and replace $terminal = alacritty
with $terminal = ghostty
. Now Super + Return
will start Ghostty! Same story for kitty.
If you'd like to match the aesthetics of the default Omarchy setup with the Tokyo Night theme in Ghostty, you can use this configuration and put it in `~
FAQ
366 words
Move Security
Open Security
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:
- Full-disk encryption is mandatory: This is the most important step to securing the physical protection of your data. If your computer is lost or stolen, the data is fully encrypted using standard LUKS (Linux Unified Key Setup).
- Firewall is enabled by default: All incoming traffic by default except for port 22 for ssh and port 53317 for LocalSend. We even lock down Docker access using the ufw-docker setup to prevent that your containers are accidentally exposed to the world.
- Arch always have the latest updates: Arch, the underlying distro that Omarchy is built on, is a rolling distribution. This means that any security vulnerability that's discovered and patched in any package is immediately a
Security
176 words
Move Omarchy on...
Omarchy on...
89 words
Move Good Linux Hardware
Good Linux Hardware
12 words