How to Create and Install Custom Omarchy Themes

The safest way to make an Omarchy theme is to copy a working theme into your user theme directory and edit the copy.

Custom themes belong in:

~/.config/omarchy/themes

Packaged themes live under:

/usr/share/omarchy/themes

Do not customize a packaged theme in place. An update can replace it.

Start from an existing theme

Choose a packaged theme that is structurally close to what you want and copy it into your user theme directory under a new name.

That gives you a known-working file layout instead of forcing you to invent one.

Once the copied theme is under ~/.config/omarchy/themes, Omarchy includes it in the theme-selection flow.

colors.toml is the main palette

The central theme file is colors.toml.

The palette defined there is used to generate or coordinate colors across supported parts of the system, including:

• terminals;
• btop;
• Chromium;
• Hyprland;
• Neovim;
• Helix;
• VS Code;
• Obsidian;
• the Omarchy shell.

That is why an Omarchy theme can change more than wallpaper and window borders.

A coherent palette propagates through multiple applications.

Change one layer at a time

A practical workflow is:

1. copy a working theme;
2. rename the theme directory;
3. edit colors.toml;
4. apply the theme;
5. inspect terminal, editor, browser and shell contrast;
6. adjust backgrounds and optional assets afterward.

Changing the palette and every asset simultaneously makes it harder to identify what caused a visual problem.

Aether provides a graphical path

Omarchy currently includes Aether for creating themes through a graphical interface.

You can launch it from the apps menu and use it to experiment with colors and backgrounds.

That is useful when you want visual iteration without manually editing the palette first.

The resulting theme still fits into the same user-owned theme system.

Themes can contain more than colors

A custom theme directory can include backgrounds and additional theme files.

Current Omarchy documentation also supports light themes through a mode = "light" declaration in colors.toml.

If you are distributing a theme, be careful with wallpaper licensing. A technically valid theme repository does not automatically give you the right to redistribute somebody else's artwork.

Apply and inspect the theme

From the menu, choose the theme through Omarchy's normal style controls.

From the CLI, current commands include:

omarchy theme list

and:

omarchy theme set <name>

Use the list command rather than assuming the directory name was interpreted exactly the way you expected.

Installed third-party themes are treated cautiously

Current Omarchy releases distinguish between your own local theme and a theme installed from somebody else's repository.

For remotely installed themes, Omarchy strips several file types capable of influencing executable behavior and regenerates those pieces from the palette.

That is a useful security boundary: installing a visual theme should not casually become permission to execute arbitrary desktop code.

Keep theme work separate from general config edits

If you are changing keybindings, monitors or input settings, those are not theme concerns.

Keep appearance in the theme and behavioral customization in the normal user configuration.

See How to Customize Omarchy Without Breaking Future Updates for that ownership model.

A good custom theme is therefore small in concept: user-owned directory, known-working structure, deliberate palette, tested contrast, optional assets.