Start here
A theme is a directory of colour
An Omarchy theme is a plain directory. It holds one colors.toml palette, usually a backgrounds/ folder, and optionally a few per-application colour files. There is no build step, no manifest, and no packaging format. If you can edit a text file and push a Git repository, you can publish a theme.
Omarchy reads your palette once and generates the configuration every themed application needs: the terminal, btop, Chromium, Hyprland, Neovim, Helix, VS Code, Obsidian, and every surface of the Omarchy shell — the bar, the menu, notifications, the on-screen display, and the lock screen. You write roughly thirty colours; Omarchy writes the rest.
Everything on these pages was checked against a real Omarchy install running version 4.0.0.alpha. Where behaviour changed between releases, both forms are described.
Where themes live
| Path | What it holds |
|---|---|
~/.config/omarchy/themes/<name>/ | Your themes, and anything installed from a Git repository. |
$OMARCHY_PATH/themes/<name>/ | Omarchy's own bundled themes. On this machine that resolves to ~/.local/share/omarchy/themes/; older installs use /usr/share/omarchy/themes/. |
~/.local/state/omarchy/current/theme/ | The staged, fully generated copy of whichever theme is active right now. Never edit this — it is rebuilt on every switch. |
~/.config/omarchy/backgrounds/<name>/ | Extra wallpapers you add to a theme without touching the theme itself. |
~/.config/omarchy/themed/*.tpl | Your own templates, for teaching Omarchy to theme an application it does not cover. |
Anything inside the first directory shows up in the theme picker. That is the entire registration mechanism.
What happens when a theme is applied
omarchy theme set <name> does the same six things every time. Knowing them explains most surprises.
- Take a lock, so two theme switches queue instead of racing, and empty the staging directory at
~/.local/state/omarchy/current/next-theme. - Copy the bundled theme of that name, if one exists.
- Overlay your copy from
~/.config/omarchy/themes/<name>/on top — in full if you wrote it, filtered if it came from a Git clone. - If the staged theme has no
colors.tomlbut does have analacritty.toml, derive a palette from the terminal colours. - Render every template in
~/.config/omarchy/themed/and then$OMARCHY_PATH/default/themed/, skipping any file the theme already supplied. - Swap the staged directory into place as
current/theme, writecurrent/theme.name, hand the palette to the running shell, then retint the applications that are already open and fire thetheme-sethook.
The fifth step is the one worth remembering: a file you ship always beats the file Omarchy would have generated. Shipping your own btop.theme means Omarchy never renders the template for it.
Two ways to start
Copy an existing theme and edit it, or start from a blank palette in a colour editor. Both end in the same place — a directory with a colors.toml in it.
- By hand: copy a bundled theme into
~/.config/omarchy/themes/, editcolors.toml, and switch to it. Step by step. - In this gallery: build a palette in the Theme Studio, watch it against a simulated desktop, check contrast as you go, and publish it as an installable repository.
- On your desktop: Omarchy ships Aether, a graphical theme builder, under
Super + Alt + Space.