How to Install a New Theme for Omarchy from a Git Repository

Clone the theme repository, copy the theme folder containing colors.toml into ~/.config/omarchy/themes/, and restart the shell to load the new palette.

Omarchy is a customizable desktop environment built on Quickshell that loads color palettes from TOML configuration files. To install a new theme for Omarchy from a git repository, you simply need to place the theme's directory in the user configuration path where the shell can discover it at startup.

Where Omarchy Discovers Themes

Omarchy searches for themes in two distinct locations according to the source code in themes/ and the session environment.

Built-in themes reside in the repository directory under themes/<theme-name>/colors.toml. The source tree includes examples such as themes/white/colors.toml and themes/nord/colors.toml.

User-installed themes live in ~/.config/omarchy/themes/<theme-name>/. At runtime, Omarchy checks the $OMARCHY_PATH environment variable first, then falls back to the user config directory, merging any custom themes it finds.

Step-by-Step Installation from Git

Clone the Theme Repository

Start by cloning the external theme repository to your local machine. The repository should contain a directory with at least a colors.toml file.

git clone https://github.com/example/omarchy-awesome-theme.git
cd omarchy-awesome-theme

Copy to the User Configuration Directory

Create the themes directory if it does not exist, then copy the theme folder into ~/.config/omarchy/themes/. The folder must contain a colors.toml file that defines the color palette.

mkdir -p ~/.config/omarchy/themes
cp -r my-awesome-theme ~/.config/omarchy/themes/

Refresh Configuration and Restart

Optionally run the omarchy-refresh-config helper script to back up existing files. This script, located at bin/omarchy-refresh-config in the repository, copies default configurations and preserves user modifications.

~/.config/omarchy/bin/omarchy-refresh-config my-awesome-theme

Finally, restart Omarchy by logging out and back in, or execute omarchy-restart-shell. Select the new theme via the command line or UI:

omarchy theme select my-awesome-theme

How Theme Loading Works Internally

Omarchy's Quickshell-based session reads the palette at startup through the internal theme module. It searches for colors.toml in the following order:

1. $OMARCHY_PATH/themes/<name>/colors.toml (built-in)
2. ~/.config/omarchy/themes/<name>/colors.toml (user-installed)

Once found, the palette values are injected into QML templates located in default/themed/*.tpl and applied to the interface. No additional registration step is required because Omarchy dynamically discovers themes at startup.

Summary

• Omarchy discovers themes in $OMARCHY_PATH/themes/ (built-in) and ~/.config/omarchy/themes/ (user-installed)
• To install from git, clone the repository and copy the theme folder to the user config directory
• Ensure the theme contains a colors.toml file at its root
• Run omarchy-refresh-config to safely back up existing configurations (optional)
• Restart the shell with omarchy-restart-shell or log out/in to load the new theme
• Select the theme using omarchy theme select <name>

Frequently Asked Questions

Do I need to run omarchy-refresh-config every time I install a theme?

No. The omarchy-refresh-config script is optional. According to the source in bin/omarchy-refresh-config, it primarily copies default files from the repository into your user config and backs up existing files. Omarchy will load the theme directly from ~/.config/omarchy/themes/ as soon as you place the folder there and restart the shell.

What files are required for a theme to work in Omarchy?

At minimum, a theme must contain a colors.toml file that defines the color palette. The file should reside in the theme's root directory, such as ~/.config/omarchy/themes/my-theme/colors.toml. Optional QML templates or assets can accompany the TOML file for advanced customization.

How does Omarchy decide which theme directory to use?

Omarchy uses a priority-based search order. It first checks the path specified in the $OMARCHY_PATH environment variable for built-in themes, then falls back to the user configuration directory at ~/.config/omarchy/themes/. If a theme exists in both locations, the built-in version takes precedence unless manually overridden.

Can I install multiple themes from different git repositories?

Yes. Simply clone each repository and copy the respective theme directories into ~/.config/omarchy/themes/. Each folder should have a unique name and contain its own colors.toml file. All installed themes will be available for selection via omarchy theme select.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}