theming

Themes, Backgrounds, and Fonts

Read this before changing themes, backgrounds, fonts, or theme colors.

Theme Commands

omarchy theme list              # Show available themes
omarchy theme current           # Show current theme
omarchy theme set <name>        # Apply theme ("Tokyo Night" and "tokyo-night" both work)
omarchy theme bg next           # Cycle background
omarchy theme install <url>     # Install from git repo

Making a New Theme

1. Create a directory under `~/.config/omarchy/themes`. 2. See how an existing theme is done via `/usr/share/omarchy/themes/catppuccin`. 3. Download a matching background (or several) from the internet and put them in `~/.config/omarchy/themes/<name-of-new-theme>/backgrounds/`. 4. When done with the theme, run `omarchy theme set "Name of new theme"`.

Additional user backgrounds for any theme (stock or custom) go in `~/.config/omarchy/backgrounds/<theme-slug>/`.

What a Theme Installed From a Repo May Not Contain

A theme the user wrote by hand in `~/.config/omarchy/themes` is unrestricted, as are Omarchy's own themes. From a theme cloned by `omarchy theme install`, Omarchy drops only what runs code: any `*.lua` (Hyprland requires a theme's `hyprland.lua` and `gum_env.lua` at login, Neovim loads `neovim.lua` at startup), the terminal configs `alacritty.toml`, `foot.ini`, `ghostty.conf` and `kitty.conf` (each names the program the terminal launches), and `vscode.json` (names a VS Code extension to install). Those are regenerated from `colors.toml` through `$OMARCHY_PATH/default/themed/*.tpl`, and named on stderr.

Everything else a cloned theme ships is kept, including `btop.theme`, `chromium.theme`, `helix.toml`, `icons.theme`, `keyboard.rgb` and `shell.toml`. Omarchy tells a cloned theme from the user's own by the `.git` directory a clone leaves behind.

To change how Omarchy themes an app for every theme, write the template rather than the theme: `~/.config/omarchy/themed/<config-name>.tpl` overrides the built-in one. See `docs/theming.md` in the Omarchy repo.

Customizing a Stock Theme

Never edit stock themes under `/usr/share/omarchy/themes/` — changes are lost on update. Two safe options:

Both write into `~/.config/omarchy/themes`, where a theme the user wrote is unrestricted — the list above applies only to a theme cloned from a repo.

**Overlay (preferred for small tweaks):** create a user theme directory with the SAME slug containing only the files you want to change. When the theme is applied, the stock theme is copied first and your files win on top:

mkdir -p ~/.config/omarchy/themes/catppuccin
cp /usr/share/omarchy/themes/catppuccin/colors.toml ~/.config/omarchy/themes/catppuccin/
# Edit the copied colors.toml, then re-apply:
omarchy theme set catppuccin

**Fork:** copy the whole stock theme under a new name for a fully independent variant:

cp -r /usr/share/omarchy/themes/catppuccin ~/.config/omarchy/themes/catppuccin-custom
# Edit ~/.config/omarchy/themes/catppuccin-custom/, then:
omarchy theme set catppuccin-custom

Fonts

omarchy font list               # Available fonts
omarchy font current            # Current font
omarchy font set <name>         # Change font