Open Welcome to Omarchy

Welcome to Omarchy!

Omarchy is an omakase distribution based on Arch Linux and 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

Open Getting Started

Getting Started

Omarchy is installed using an ISO. It's designed for a dedicated drive, so dual-booting should only happen if you have two disks in your machine. The installation will wipe the selected drive and use full-disk encryption, so be sure to take a backup before using an existing drive!

Download the Omarchy Online ISO first, put it on a USB stick (use balenaEtcher on Mac/Windows or caligula on Linux), and boot off the stick.

Remember that many PCs ship with Secure Boot and/or TPM on in the BIOS. You have to turn these off to be able to install Omarchy. They're Microsoft security schemes meant for Windows and Microsoft-affiliated Linux distributions.

Then answer the configuration questions, and confirm them like this:

Then select a drive for your installation, and sit back and watch the installation show go. It tak

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 application launcher and Super + Alt + Space to open the Omarchy Menu. These two commands allow you to do just about everything.

But the application launcher 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 `Super + Shift + Arro

Open Themes

Themes

Omarchy comes with eleven beautiful themes. You can select between them from Style > Theme in the Omarchy Menu (Super + Alt + Space) or hop directly to the selector using Super + Ctrl + Shift + Space. Each theme styles the desktop, terminal, neovim, activity screen (btop), notifications (mako), top bar (waybar), application launcher (walker), and the lock screen (hyprlock).

Most themes have a set of background images that you can rotate between using Super + Ctrl + Space.

You can find even more themes on the extra themes page or even make your own theme.

Tokyo Night

Catppuccin

Everforest

Gruvbox

Osaka Jade

![kanagawa.png](/u/kanagawa-qNheh

Open Hotkeys

Hotkeys

You can see all the main keyboard bindings by hitting Super + K.

Navigating

Hotkey	Function
Super + Space	Application launcher
Super + Alt + Space	Omarchy control menu
Super + Escape	Lock/suspend/relaunch/restart/shutdown computer
Super + W	Close window
Ctrl + Alt + Del	Close all windows
Super + 1/2/3/4	Jump to specific workspace
Super + Tab	Jump to next workspace
Super + Shift + Tab	Jump to previous workspace
Super + Ctrl + Tab	Jump to former workspace
Shift + Super + 1/2/3/4	Move window to workspace
Ctrl + 1/2/3/..	Jump to browser tab
F11	Go full screen
Shift + F11	Force full screen on apps like Spotify
Alt + F11	Go full width for the window

Open Neovim

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!

If you're totally new to vim-style editing, I recommend you checkout ThePrimeagen's Vim As Your Editor series on YouTube. That'll teach you the basics. Just know that unlike more similar mainstream editors, it's going to take you longer to get basic proficiency with vim. But once you do, the payoff is also larger.

Now Neovim is basically infinitely configurable. If you really want to go nuts, you can create your own Neovim configuration from scratch. There's a great course from [Typecraft on setting up Neovim from scratch](http

Open Shell Tools

Shell Tools

man

The man tool is a built-in Linux command that displays detailed manual pages (aka man pages) for other commands, helping you learn their usage and options. Just type man followed by a command name, like man ls, to quickly access clear documentation right in your terminal.

fzf

fzf gives you fuzzy finding of files via the ff alias. Go to any directory, type ff, and you'll be able to fuzzy find your way to any file in that tree, while seeing a preview of the files you're narrowing down on the right-hand side.

You can use Ctrl + R to use fzf to fuzzy find through your command history.

This tool is also used by Neovim when you type Space Space.

The full manual can be found via man fzf.

Zoxide

Zoxide is a replacement for cd. It remembers the directories you've been in, so you can more easily jump to them next time. Say you do cd ~/.local/share/omarchy once. Next time, you

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!
• img2jpg: Turn any image into a near-full quality jpg.
• img2jpg-small: Turn any image into near-full quality 1080p-wide jpg.
• img2png: Turn any image into a lossly-compressed PNG.

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

Open GUIs

GUIs

Obsidian

Obsidian is a free and highly extensible note taking application that uses simple Markdown files for storage.

Obsidian is free for all purposes, including personal, commercial, and non-profit use.

Obsidian also offers a commercial add-on for syncing with mobile apps on iOS and Android. (https://obsidian.md/pricing).

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.

Libr

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

Open Development Tools

Development Tools

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, you can run the Omarchy Menu (Super + Alt + Space) and see the options under Install > Editor. We have VSCode, Cursor, Zed, Sublime Text, and Helix 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).

You can set the system-wide default editor under Setup > Defaults. That'll open the UWSM defaults file, which controls both editor and terminal. After you save your change, you have to relaunch Hyprland for it to take affect (Super + Esc).

T

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.

Open Web Apps

Web Apps

You can add your own web apps using Install > Web App in the Omarchy menu (Super + Alt + Space). It'll ask you for the app name, app URL, and then the icon URL. You can get great PNG icons for many popular web apps on Dashboard Icons.

They'll then be accessible through the app launcher (Super + Space), and use the beautiful frameless web-app window.

If you wish to remove a web app, just go to Remove > Web App in the Omarchy menu.

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.

When you're in a web app, you can copy the current URL to the clipboard using Shift + Alt + L.

By default, Omarchy already ships with an assortment of default apps:

HEY

HEY is an emai

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 > Gaming > 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 pro

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 Arch 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 sudo pacman -S [package] in the terminal).

You can do the same with AUR, just use Install > AUR. Just remember that the AUR isn't vetted by the Arch team. It's like RubyGems or npm. Anyone can upload.

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 sudo pacman -Rns [package]).

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:

File	Purpose
~/.config/hypr/hyprland.conf	Controls keybindings, default apps, and everything Hyprland. Learn more about Hyprland configs.

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).

You can install other popular programming fonts via Install > Style > Font in the Omarchy menu.

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

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 

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 > Security > 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 `su

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.

You can do this most easily by going to Install > Style > Background in the Omarchy Menu. That'll bring up the folder where the backgrounds for that theme is stored. Hit Super + F to start another file manager, find your background, copy it over. Now it'll be included in the cycle of backgrounds you can move between using Super + Ctrl + Space.

You can find a huge collection of cool curated backgrounds on https://github.com/dharmx/walls.

Open Prompt

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.

If you want more information or style, you can change the Starship.rs configuration in ~/.config/starship.toml. There's a lot you can do. Just don't go overboard (or do go overboard, do whatever you want, it's your computer!)

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 pulls the latest Omarchy code, runs any pending migrations to get your system in sync with the latest, and then updates all system packages from both the official Arch repository, the Omarchy Package Repository, and the AUR.

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.

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.

Aetheria

Arc Blueberry

Ash

Aura

All Hallow's Eve

Ayaka

![azure-glow-theme.png

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

Open Manual installation

Manual installation

If you can't use the Omarchy ISO, you can do a manual installation using the vanilla arch ISO, archinstall, and following the steps in this guide. This is not something most people should attempt, but if you know what you're doing, and why you're doing it, this is how.

1. 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!).
2. 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.
3. 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 (with

Open Mac Support

Mac Support

As of v3.0.0, 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.

Please note that installing on an M-series Mac is not directly supported at this time. You can find out more about the state of this in #omarchy-on-other in our Discord.

In a simple test, we were able to achieve 36% performance gains on a 2019 MacBook Pro just by installing Omarchy.

Installing Omarchy on Mac

Omarchy only supports being the only OS installed at the moment. During the installation, the drive will be wiped and MacOS will no longer be bootable.

You can still restore it later via Internet Recovery if you'd like.

For the sake of this part, we'll assume you've already reviewed [Getting Started](https://learn.omacom.

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

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 clock format to 12-hour?

Edit your ~/.config/waybar/config.jsonc file and replace this:

  "clock": {
    "format": "{:%A %H:%M}",

with:

  "clock": {
    "format": "{:%A %I:%M %p}",

This will display Sunday 10:55 AM.

---

How do I get the speakers + webcam working on my Apple Studio Display?

You'd think that it should all work just plugging in USB C, but unfortunately that isn't the case. The solution I've found to make it work reliably is using

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:

1. 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).
2. 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.
3. 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

Open Omarchy on...

Omarchy on...

Apple M1/M2 chips

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.

Apple Virtual Machine

You can also install Omarchy inside a Parallels VM. Quite the cumbersome process, but there's a user-driven guide for that too.

VirtualBox

VirtualBox is a popular VM runner. You can run Omarchy inside that too. But performance probably won't be great.

VMware Workstation on Windows 11

Another popular VM runner for Windows. Omarchy has been setup inside of that as well.

CachyOS

CachyOS is a fork of Arch with a range of performance optimizations applied. I was never