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

> Install a new Omarchy theme from a Git repository easily. Clone the theme, place it in the config directory, and restart your shell to apply the new palette.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-26

---

**Clone the theme repository, copy the theme folder containing [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/themes/white/colors.toml) and [`themes/nord/colors.toml`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file.

```bash
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`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file that defines the color palette.

```bash
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.

```bash
~/.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:

```bash
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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file. All installed themes will be available for selection via `omarchy theme select`.