Open Getting Started

Getting Started

Before installing Omarchy, you might want to consider Omakub, if you're new to Linux. It's based on a more conventional desktop environment and built on top of Ubuntu — the most popular Linux distribution. It's less intimidating and less nerdy. But if you really are ready for the acquired tastes of Omarchy, go on.

Omarchy runs on Arch, so you must install that first:

1. Download the Arch ISO, put it on a USB stick, and boot into the installer.
2. If you're on wifi, run iwctl, then type 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 make sure you setup disk encryption. Omarchy relies exclusively on disk encryption to secure your device, as it'll auto-login the user after the disk has been decrypted at boot. Under Audio, pick pipewire. Under Network configuration, pick Copy ISO network configuation. Under

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 wofi application launcher. That'll show you everything that's installed on the system.

But wofi is not even intended to be the main way to operate the system. 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 + Arrow Right while on the browser to swap the windows.

Open Themes

Themes

Omarchy comes with six beautiful themes. You can cycle through them using Super + Ctrl + Shift + Space. Each theme styles the desktop, terminal, neovim, btop, notifications (mako), top bar (waybar), application launcher (wofi), and the lock screen (hyprlock).

You can add your own themes in ~/.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 rotation when you cycle through the themes.

Each theme can have a set of background images that you can rotate between

Open Hotkeys

Hotkeys

Navigating

Hotkey	Function
Super + Space	Type app to launch
Super + W	Close window
Super + 1/2/3/4	Jump to workspace
Shift + Super + 1/2/3/4	Move window to workspace
Ctrl + 1/2/3/..	Jump to browser tab
F11	Go full screen
Super + Arrow	Move focus to window in direction of arrow
Super + Shift + Arrow	Swap window with another in direction of arrow
Super + Equal	Grow windows to the left
Super + Minus	Grow windows to the right
Super + Shift + Equal	Grow windows to the top
Super + Shift + Minus	Grow windows to the bottom

Launching apps

Hotkey	Function
Super + Return	Terminal

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

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.

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/omakub once. Next time, you can just do cd omakub, 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 Neovim when you type `Space

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.
• web2app [Name] [URL] [URL to PNG icon]: Create a .desktop file for a web app that can then be started with wofi easily.
• web2app-remove [Name]: Remove the .desktop file you've previously created for a web app.
• fix_fkeys: Use F-keys instead of built-in functions for keyboards like the Lofree Flow84.

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 lzg. 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 netw

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 wofi (Super + Space).

LibreOffice

LibreOffice is a complete office package with word processor, spreadsheet, presentations, drawing application, and more. It's compatible with files from Microsoft Office, so this is a great way to be able to open those Word documents.

You start LibreO

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.

Dr

Open Development Tools

Development Tools

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 install ruby@3.3. Or, if your project has a .ruby-version file, you can just run mise i in the root of that project.

Mise works for Ruby, Python, Go, Java, Elixir, Node.js. By default, Omarchy just installs the latest version of Ruby.

GitHub CLI

The GitHub CLI let's you authenticate with your GitHub account and clone private repositories using it. To authenticate, run gh auth login. Then you can checkout private repositories using gh repo clone org/repo.

You can also perform a bunch of other GitHub operations using this command. Just run gh to see everything that's possible.

Docker

Docker hardly needs any introduction.

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/hyprland.conf.

ChatGPT

ChatGPT is the most popular AI chat bot in the world.

You can start ChatGPT using Super + A.

WhatsApp

WhatsApp is one of the most popular messaging services in the world, and the web version is a great option for Linux.

You can start WhatsApp using Super + Shift + G.

X

X is where news break.

You can start X using Super + X and go straight to writing a new post with Super + Shift + X.

YouTube

[YouTube](https://y

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 with yay -S [package]. If there are multiple matches, you'll just pick yourself.

If you want to remove a package, you can use yay -Rns [package] (removes package, config files, and dependencies).

Here are some common packages you might like:

Program	Description	Package
Cursor	AI-powered editor	cursor-bin
Claude Code	AI-assist in the terminal	claude-code
Steam	Game distribution platform	steam
Minecraft	Everyone's favorite digital LEGOs	minecraft-launcher

Go to https://aur.archlinux.org/packages to see everything. Almost a hundred thousand packages!

Open Dotfiles

Dotfiles

Omarchy is primarily configured through the so-called dotfiles that live in ~/.config. Here's a list of the key files and what they control:

File	Purpose
~/.config/hypr/hyprland.conf	Controls keybindings, default apps, and everything Hyprland. Learn more about Hyprland configs.
~/.config/hypr/monitors.conf	Controls your monitors, resolution, and position.
~/.config/hypr/hypridle.conf	Controls your idle/sleep settings. Shouldn't need touching.
~/.config/hypr/hyprlock.conf	Controls your lock screen, but this is symlinked to your theme for styling.
~/.config/waybar/config	Controls your top bar that's run with waybar. Learn more about Waybar configs.
~/.config/waybar/style.css	Controls your top bar design, but it's symlinked to your theme.
`~/.config/wofi

Open FAQ

FAQ

Why is VLC 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 + Shift + Escape).

Why are my external speakers not playing?

Probably because they're not set as the primary output. Click on the speaker in the top right of the waybar, and it'll launch the volume controls where you can select the primary speaker.

How do I switch between keyboard layouts?

Edit your ~/.config/hypr/hyprland.conf file and add this to switch between layouts on Alt + Space:

# Use multiple keyboard layouts and switch between them with Alt + Space
input {
    kb_layout = us,fr
    kb_options = compose:caps,grp:alt_space_toggle
}

Why is Dropbox complains about tray access?

Just ignore it. Omarchy uses its own Dropbox icon via waybar. You don't need the tray access. You can do all your manag

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 with omarchy-update.

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.

Open Good Linux Hardware

Good Linux Hardware

Once upon a time, it was a pain to find hardware where everything just worked out of the box with Linux. Those days are long gone. There are now fantastic computer makers, like Framework, System76, and TUXEDO, who all specialize in making Linux-compatible systems.

But it also just doesn't matter as much as it once did. Most of the new miniPCs from makers such as Beelink and Minisforum work great with Linux, even if its not necessarily a big priority for the companies themselves. AMD-based systems in particular have been doing very well in this regard, because AMD simply invests a lot to make sure that their latest chips are fully supported with the latest kernels.

We're spoiled for choice these days, but here's what I'd recommend:

• Framework 13: This is the best Linux laptop I've tried so far. It's be