FIELD NOTE / 01
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.
FIELD NOTE / 02
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.
FIELD NOTE / 03
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.
FIELD NOTE / 04
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.