Omarchy 3.8 Guide

Omarchy is a beautiful, modern, opinionated Linux distribution by DHH, built on Arch Linux with the Hyprland Wayland compositor.

Architecture

Layer	Component	Config Location
Base OS	Arch Linux	`/etc/`, `~/.config/`
Display server	Hyprland (Wayland)	`~/.config/hypr/`
Bar	Waybar	`~/.config/waybar/`
Launcher	Walker	`~/.config/walker/`
Notifications	Mako	`~/.config/mako/`
Terminal	Alacritty / Foot / Kitty / Ghostty	`~/.config/<terminal>/`
Shell	zsh with starship prompt	`~/.config/starship.toml`

File system layout

~/.local/share/omarchy/     # READ-ONLY — system defaults, never edit here
├── bin/                    # omarchy command scripts
├── config/                 # Default config templates for waybar, walker, etc.
├── themes/                 # Stock theme files
├── default/                # Hyprland default configs
│   └── hypr/               #   autostart, bindings, envs, input, looknfeel, windows
├── migrations/             # Version migrations
└── install/                # Installation scripts

~/.config/                  # SAFE TO EDIT — user configuration
├── hypr/
│   ├── hyprland.conf       # Main config (sources defaults + overrides)
│   ├── monitors.conf       # Display/monitor setup
│   ├── input.conf          # Keyboard, mouse, touchpad
│   ├── bindings.conf       # Custom keybindings
│   ├── looknfeel.conf      # Gaps, borders, animations, opacity
│   ├── autostart.conf      # Startup applications
│   ├── hypridle.conf       # Idle/lock/suspend
│   ├── hyprlock.conf       # Lock screen appearance
│   └── hyprsunset.conf     # Night light
├── waybar/
│   ├── config.jsonc        # Bar layout and modules
│   └── style.css           # Bar styling
├── walker/
│   └── config.toml         # App launcher config
├── mako/
│   └── config              # Notification daemon config
├── omarchy/
│   ├── themes/<name>/      # Custom themes
│   └── hooks/              # Automation hooks
└── <terminal>/
    └── <config>            # Terminal config

The `omarchy` CLI

The single omarchy command dispatches to all sub-commands. Use --help freely.

omarchy --help               # Full command list
omarchy commands             # All commands + descriptions
omarchy <group> --help       # Commands in a group
omarchy <group> <action> --help  # Specific command help
omarchy commands --json      # Machine-readable listing

Command groups

Group	Purpose	Common commands
`omarchy theme`	Theme management	`list`, `current`, `set`, `bg next`, `install`
`omarchy refresh`	Reset configs	`waybar`, `hyprland`, `walker`, `config <path>`
`omarchy restart`	Restart services	`waybar`, `hyprctl`, `terminal`, `walker`, `mako`
`omarchy toggle`	Toggle features	`nightlight`, `touchpad`, `waybar`, `idle`, `screensaver`, `suspend`
`omarchy install`	Install software	`browser`, `dev-env`, `terminal`, `gaming`, `vscode`, `zed`, `helix`, `tailscale`, `nordvpn`
`omarchy launch`	Launch apps	`browser`, `editor`, `walker`, `floating terminal with presentation`, `or focus`
`omarchy capture`	Screenshots/recordings	`screenshot`, `screenrecord`
`omarchy system`	System control	`lock`, `logout`, `reboot`, `shutdown`, `wake`
`omarchy pkg`	Package management	`add`, `aur add`, `drop`, `install`, `remove`
`omarchy update`	System updates	`-y`, `firmware`, `perform`
`omarchy menu`	Interactive menus	`keybindings`, `file`, `input`, `select`
`omarchy setup`	Initial configuration	`dns`, `security fingerprint`, `security fido2`
`omarchy snapshot`	System snapshots	`create`, `restore`
`omarchy voxtype`	Dictation	`install`, `remove`, `config`, `model`, `status`
`omarchy webapp`	Web app management	`install`, `remove`, `handler`
`omarchy tui`	TUI launcher management	`install`, `remove`
`omarchy hw`	Hardware detection	`intel`, `nvidia`, `touchpad`, `touchscreen`, `hybrid gpu`, `match`
`omarchy reminder`	Desktop reminders	`<minutes> [message]`, `show`, `clear`
`omarchy share`	LocalSend sharing	`clipboard`, `file`, `folder`
`omarchy swayosd`	On-screen display	`brightness`, `kbd brightness`, `client`
`omarchy sudo`	Sudo management	`keepalive`, `passwordless`, `reset`
`omarchy powerprofiles`	Power management	`list`, `set`, `init`
`omarchy migrate`	Run pending migrations	(no subcommands)

Command helpers

omarchy notification send <glyph> <headline> [description]     # Send a desktop notification
omarchy show done                                               # "Done!" spinner
omarchy show logo                                               # Print Omarchy logo
omarchy debug --no-sudo --print                                 # Debug info (always use these flags)

Themes

Available themes (19 stock)

Catppuccin, Catppuccin Latte, Ethereal, Everforest, Flexoki Light, Gruvbox, Hackerman, Kanagawa, Lumon, Matte Black, Miasma, Nord, Osaka Jade, Retro 82, Ristretto, Rose Pine, Tokyo Night, Vantablack, White

Commands

omarchy theme list              # List available themes
omarchy theme current           # Show current theme
omarchy theme set "Tokyo Night" # Apply a theme (use display name)
omarchy theme bg next           # Cycle wallpaper
omarchy theme bg set ~/image.png # Set specific wallpaper
omarchy theme bg install        # Open theme's background folder
omarchy theme install <url>     # Install theme from git repo
omarchy theme update            # Update all git-installed themes
omarchy theme remove <name>     # Remove a user-installed theme
omarchy theme refresh           # Re-apply current theme from templates

Making a custom theme

# 1. Create a theme directory
mkdir -p ~/.config/omarchy/themes/my-custom-theme

# 2. Copy an existing theme as reference
ls ~/.local/share/omarchy/themes/tokyo-night/

# 3. Add wallpapers
#    Download images into ~/.config/omarchy/themes/my-custom-theme/

# 4. Apply it
omarchy theme set "my-custom-theme"   # Uses directory name

Theme hooks

Run custom scripts automatically when the theme changes:

# Create the hooks directory
mkdir -p ~/.config/omarchy/hooks

# Create a theme-set hook
cat > ~/.config/omarchy/hooks/theme-set << 'EOF'
#!/bin/bash
THEME_NAME=$1
echo "Theme changed to: $THEME_NAME"
# Add your custom actions here
EOF
chmod +x ~/.config/omarchy/hooks/theme-set

Other available hooks: font-set (runs after font change), post-update (runs after omarchy update).

Keybindings

Default modifier: `SUPER` (Windows/Command key)

Hyprland keybindings use bindd (bound with description — appears in the keybinding menu) and bind. Learn the grammar:

bind[d] = <MODIFIERS>, <KEY>, [DESCRIPTION], <ACTION>

Application launchers (`SUPER + SHIFT + KEY`)

Key	App
`Return`	Terminal (in cwd)
`F`	File manager (Nautilus)
`B`	Browser
`M`	Music (Spotify)
`N`	Editor ($EDITOR)
`D`	Docker (lazydocker TUI)
`G`	Signal
`O`	Obsidian
`W`	Typora
`/`	Passwords (1Password)
`A`	ChatGPT web app
`C`	Calendar web app
`E`	Email web app
`Y`	YouTube web app
`P`	Google Photos web app
`X`	X / Twitter web app

Variants: add ALT for alternative apps (e.g. SUPER + SHIFT + ALT + A = Grok, SUPER + SHIFT + ALT + M = Music TUI, SUPER + SHIFT + ALT + G = WhatsApp, SUPER + SHIFT + CTRL + G = Google Messages, SUPER + SHIFT + ALT + X = X Post composer).

Window management

Key	Action
`SUPER + Q`	Close active window
`SUPER + F`	Toggle fullscreen
`SUPER + V`	Toggle floating
`SUPER + P`	Toggle pin (always on top)
`SUPER + J`	Toggle split direction
`SUPER + Space`	Toggle layout (dwindle ↔ master)
`SUPER + Z`	Toggle window group (tab)
`SUPER + .`	Toggle group toggles
`SUPER + TAB`	Cycle through windows
`SUPER + arrows / hjkl`	Navigate focus between windows
`SUPER + SHIFT + arrows / hjkl`	Move window in direction
`SUPER + 1-9`	Switch workspace by number
`SUPER + SHIFT + 1-9`	Move window to workspace
`SUPER + mouse scroll`	Cycle through workspaces
`SUPER + SHIFT + mouse scroll`	Move window to workspace
`SUPER + S`	Toggle scratchpad (overview of minimised windows)
`SUPER + Backspace`	Toggle split ratio

Resizing

Key	Action
`SUPER + L`	Enter/exit resize mode
In resize mode: arrows/hjkl	Resize by 10px
`SUPER + SHIFT + arrows`	Resize by 10px (no mode)
`SUPER + SHIFT + R`	Reset window size

Media and volume

Key	Action
`XF86AudioRaiseVolume` / `XF86AudioLowerVolume`	Volume up/down (swayosd)
`XF86AudioMute`	Mute toggle (swayosd)
`XF86AudioMicMute`	Mic mute toggle
`XF86AudioPlay` / `XF86AudioPause` / `XF86AudioNext` / `XF86AudioPrev`	Media controls
`SUPER + SHIFT + V`	Volume mixer (wireplumber)

Brightness

Key	Action
`XF86MonBrightnessUp` / `XF86MonBrightnessDown`	Display brightness (swayosd)
`XF86KbdBrightnessUp` / `XF86KbdBrightnessDown`	Keyboard brightness (swayosd)

System

Key	Action
`SUPER + Escape`	Lock screen
`SUPER + SHIFT + Q`	Log out
`SUPER + SHIFT + Escape`	Power menu (lock/logout/reboot/shutdown)
`SUPER + Space` (with Walker)	Omarchy Menu — search everything (apps, settings, commands)
`SUPER + SHIFT + T`	Toggle touchpad
`SUPER + SHIFT + U`	Toggle night light
`SUPER + SHIFT + I`	Toggle idle locking
`SUPER + SHIFT + W`	Toggle waybar
`SUPER + Return`	Terminal
`SUPER + SHIFT + S`	Screenshot region
`SUPER + SHIFT + ALT + S`	Full screenshot
`SUPER + SHIFT + R`	Screen recording (region)
`SUPER + SHIFT + ALT + R`	Screen recording (full)

Window groups (tabbed)

Key	Action
`SUPER + G`	Toggle group
`SUPER + SHIFT + G`	Lock/unlock group
`SUPER + TAB`	Next window in group
`SUPER + SHIFT + TAB`	Previous window in group

Mouse

Action	Behaviour
Click window	Focus
`SUPER + click`	Move floating window
`SUPER + right-click`	Resize floating window
`SUPER + scroll`	Cycle workspaces
`SUPER + SHIFT + scroll`	Move window to workspace
Double-click titlebar	Toggle maximize

Customising bindings

Edit ~/.config/hypr/bindings.conf:

# Add a new binding
bind = SUPER, E, exec, nautilus

# Override an existing binding — always unbind first
unbind = SUPER, F
bind = SUPER, F, exec, my-other-file-manager

View current bindings: omarchy menu keybindings --print

Hyprland configuration

Config loading order

~/.local/share/omarchy/default/hypr/*        ← System defaults (read-only)
~/.config/omarchy/current/theme/hyprland.conf ← Current theme overrides
~/.config/hypr/monitors.conf                  ← Your monitor setup
~/.config/hypr/input.conf                     ← Your input settings
~/.config/hypr/bindings.conf                  ← Your keybindings
~/.config/hypr/looknfeel.conf                 ← Your appearance tweaks
~/.config/hypr/autostart.conf                 ← Your startup apps
~/.local/state/omarchy/toggles/hypr/*.conf    ← Dynamic toggles

Important config files in `~/.config/hypr/`

File	Purpose	Key settings
`monitors.conf`	Display configuration	Resolution, refresh rate, position, scale, enable/disable
`input.conf`	Keyboard, mouse, touchpad	Layout, repeat rate, touchpad speed, natural scroll
`bindings.conf`	Custom keybindings	Application shortcuts, workspace binds
`looknfeel.conf`	Appearance	Gaps, border size, border colour, blur, opacity, animations
`autostart.conf`	Startup apps	Apps to launch on login
`hypridle.conf`	Idle behaviour	Timeouts for lock, dpms off, suspend
`hyprlock.conf`	Lock screen	Background, clock, colours
`hyprsunset.conf`	Night light	Temperature shift, schedule

Managing configs

# Validate config after changes
hyprctl reload && hyprctl configerrors

# Reset specific config to defaults (backs up first)
omarchy refresh config hypr/hyprland.conf

# Reset all Hyprland configs
omarchy refresh hyprland

# Quick reload after edit
omarchy restart hyprctl

Window rules

Rules go in ~/.config/hypr/hyprland.conf or a sourced file. Always check the Hyprland Window Rules wiki for current syntax before writing rules — the format changes between versions.

Waybar

The status bar sits at the top of the screen by default.

Default modules

┌─────────────────────────────────────────────────────────────────────┐
│ ◆ │ 1  2  3  4        Mon 12:00  ☀ 12°     ⬆            │
└─────────────────────────────────────────────────────────────────────┘

Section	Modules
Left	Omarchy logo, workspace indicators
Centre	Clock, weather, update indicator, voxtype, recording indicator, idle/notification toggles
Right	Tray expander, bluetooth, network, volume, CPU, battery

Managing Waybar

omarchy restart waybar          # Apply config/style changes
omarchy refresh waybar          # Reset to defaults
omarchy toggle waybar           # Show/hide

Edit ~/.config/waybar/config.jsonc for layout, ~/.config/waybar/style.css for colours/fonts.

Walker (app launcher)

Walker serves as both the Omarchy Menu and a general application launcher.

omarchy launch walker           # Open launcher (Super + Space)
omarchy restart walker          # Apply config changes
omarchy refresh walker          # Reset to defaults

Config: ~/.config/walker/config.toml

Toggles

Omarchy uses flag files in ~/.local/state/omarchy/toggles/ to enable/disable features.

omarchy toggle nightlight       # Blue light filter on/off
omarchy toggle idle             # Auto-lock on/off
omarchy toggle touchpad         # Touchpad on/off
omarchy toggle touchscreen      # Touch input on/off
omarchy toggle waybar           # Bar visibility
omarchy toggle screensaver      # Screensaver availability
omarchy toggle suspend          # Suspend in system menu
omarchy toggle notification silencing  # Do-not-disturb
omarchy toggle hybrid gpu       # Switch GPU mode (hybrid laptops)

# Custom toggles
omarchy toggle <flag-name>      # Create your own
omarchy toggle enabled <name>   # Check if enabled
omarchy toggle disabled <name>  # Check if disabled

# Hyprland-specific
omarchy hyprland toggle <flag>  # Toggle permanent Hyprland flags
omarchy hyprland window gaps toggle  # Toggle all gaps on/off
omarchy hyprland window transparency toggle  # Toggle active window transparency

System management

omarchy update                          # Full system update
omarchy update -y                       # Non-interactive update
omarchy update firmware                 # Update firmware via fwupd
omarchy update analyze logs             # Check update logs for issues
omarchy system lock                     # Lock screen immediately
omarchy system logout                   # Log out
omarchy system reboot                   # Reboot
omarchy system shutdown                 # Shut down
omarchy system wake                     # Wake displays after idle

omarchy setup dns                       # Configure DNS
omarchy setup security fingerprint      # Fingerprint auth
omarchy setup security fido2            # FIDO2 auth

omarchy snapshot create                 # System snapshot (snapper)
omarchy snapshot restore                # Restore snapshot

Package management

omarchy pkg add <packages...>           # Install Arch packages
omarchy pkg aur add <packages...>       # Install AUR packages
omarchy pkg drop <packages...>          # Remove packages
omarchy pkg install                     # Interactive TUI picker
omarchy pkg missing <packages...>       # Check if not installed
omarchy pkg present <packages...>       # Check if installed

Installing software

Omarchy has dedicated install commands for common software:

omarchy install browser firefox         # Install Firefox
omarchy install browser chrome          # Install Chrome
omarchy install terminal ghostty        # Install Ghostty terminal
omarchy install dev-env node            # Node.js development environment
omarchy install dev-env rust            # Rust toolchain
omarchy install dev-env python          # Python + tools
omarchy install vscode                  # VS Code with Omarchy theme
omarchy install zed                     # Zed editor
omarchy install helix                   # Helix editor
omarchy install gaming steam            # Steam + graphics drivers
omarchy install gaming heroic           # Heroic Games Launcher
omarchy install gaming lutris           # Lutris + Wine
omarchy install gaming retroarch        # RetroArch + libretro cores
omarchy install tailscale               # Tailscale VPN
omarchy install nordvpn                 # NordVPN
omarchy install docker dbs              # Docker database containers
omarchy install dropbox                 # Dropbox daemon
omarchy install once                    # ONCE service
omarchy setup security fingerprint      # Fingerprint auth
omarchy setup security fido2            # FIDO2 auth

Hardware detection

omarchy hw intel                        # Is CPU Intel?
omarchy hw nvidia gsp                   # NVIDIA GPU with GSP?
omarchy hw hybrid gpu                   # Hybrid GPU active?
omarchy hw touchpad                     # Print touchpad device name
omarchy hw touchscreen                  # Print touchscreen device name
omarchy hw match "XPS"                  # Match DMI product name
omarchy hw external monitors            # External monitor connected?

Capture (screenshots/recording)

omarchy capture screenshot              # Full screen
omarchy capture region                  # Region select
omarchy capture screenrecording         # Record region
omarchy capture full screenrecording    # Record full screen

Aliases: omarchy screenshot, omarchy screenrecord.

Web apps and TUIs

Omarchy treats web apps and TUI applications as first-class citizens with desktop launchers:

# Install a web app
omarchy webapp install "My App" "https://example.com" "icon-name"

# Install a TUI launcher
omarchy tui install "htop" "uwsm-app -- xdg-terminal-exec htop"

# Remove
omarchy webapp remove "My App"
omarchy tui remove "htop"

Reminders

omarchy reminder 15 "Pick up Jack"      # 15-minute reminder
omarchy reminder show                   # List pending reminders
omarchy reminder clear                  # Clear all reminders

Mako (notifications)

omarchy restart mako                    # Apply config changes
omarchy toggle notification silencing   # Do-not-disturb mode

Config: ~/.config/mako/config

Fonts

omarchy font list                       # Available fonts
omarchy font current                    # Current font
omarchy font set "JetBrains Mono"       # Change font

Network

omarchy launch wifi                     # Wi-Fi TUI (Impala)
omarchy launch bluetooth                # Bluetooth TUI (bluetui)
omarchy restart wifi                    # Restart Wi-Fi
omarchy restart bluetooth               # Restart Bluetooth
omarchy wifi powersave on               # Toggle Wi-Fi power saving

Audio

omarchy launch audio                    # Audio controls TUI (wiremix)
omarchy restart pipewire                # Restart audio (fix issues)

Night light

omarchy toggle nightlight               # Toggle on/off
omarchy restart hyprsunset              # Apply config changes
omarchy refresh hyprsunset              # Reset to defaults

Config: ~/.config/hypr/hyprsunset.conf

Idle and lock

omarchy toggle idle                     # Enable/disable auto-lock
omarchy system lock                     # Lock immediately
omarchy restart hypridle                # Apply config changes

Config: ~/.config/hypr/hypridle.conf (idle timeouts), ~/.config/hypr/hyprlock.conf (lock screen appearance).

Troubleshooting

# Debug info (always use --no-sudo --print to avoid prompts)
omarchy debug --no-sudo --print

# Check Hyprland config for errors
hyprctl reload && hyprctl configerrors

# Upload logs for support
omarchy upload log

# Reset specific component to defaults (backs up current)
omarchy refresh waybar
omarchy refresh hyprland
omarchy refresh config hypr/hyprlock.conf

# Full reset of all Omarchy configs
omarchy reinstall configs

# Nuclear option — reinstall everything
omarchy reinstall

Version info

omarchy version                         # Omarchy version
omarchy version branch                  # Git branch
omarchy version channel                 # Package channel
omarchy version pkgs                    # Last package upgrade time

Quick reference

# Daily use
omarchy theme set "Tokyo Night"         # Change theme
omarchy theme bg next                   # Next wallpaper
omarchy toggle nightlight               # Night light
omarchy toggle touchpad                 # Touchpad
omarchy update                          # System update
omarchy system lock                     # Lock screen

# After config edits
omarchy restart waybar                  # Apply Waybar changes
hyprctl reload && hyprctl configerrors  # Apply + validate Hyprland changes
omarchy restart terminal                # Apply terminal changes

# Finding things
omarchy menu keybindings                # Search keybindings
omarchy launch walker                   # App launcher (Super + Space)

# Getting help
omarchy --help                          # All commands
omarchy <command> --help                # Specific command help