# How the Omarchy Theming System Works: A Deep Dive Into Themes, Templates, and Color Pipelines

> Explore the Omarchy theming system and its layered pipeline. Learn how palette files transform into desktop themes via template rendering and custom color helpers.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: deep-dive
- Published: 2026-08-31

---

**Omarchy's theming system uses a layered pipeline that transforms palette files (particularly [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)) into fully-rendered desktop themes through template rendering with custom color helpers and a secure staging process.**

The Omarchy distribution provides a sophisticated theming engine for Linux desktop environments. This system enables users and theme authors to define color palettes once, then automatically generate consistent configurations across shells, window managers, terminals, and system tools. Understanding how the Omarchy theming system works is essential for anyone customizing their desktop or creating shareable themes.

## How Theme Sources Are Organized

Themes in Omarchy follow a hierarchical structure with clear precedence rules.

### Built-in and User Theme Locations

System themes reside in `/usr/share/omarchy/themes/<name>/` corresponding to the repository's `themes/<name>/` directory. Users can override or extend these by creating themes in `~/.config/omarchy/themes/<name>/`【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L3-L5】.

Every theme requires a **[`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)** file defining the color palette. Optional files include:

- [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) — Shell appearance configuration
- [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) — Hyprland window manager settings
- `icons.theme` — Icon theme specification
- Background images and other assets

## The Theme Activation Pipeline

Running `omarchy-theme-set <name>` executes a carefully sequenced activation flow. This command creates a clean staging area at `~/.local/state/omarchy/current/next-theme` before committing changes【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L20-L28】.

### Step-by-Step Activation Process

1. **Copy base theme** — The built-in theme files are copied from `themes/<name>/`.

2. **Apply user overrides** — Files from `~/.config/omarchy/themes/<name>/` are overlaid, with security filtering applied for Git-installed themes (see Security section below).

3. **Generate missing palette** — If [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) is absent, Omarchy generates one from an [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) file if present.

4. **Render templates** — The **`omarchy-theme-set-templates`** command processes all `*.tpl` files, substituting color placeholders with actual values.

5. **Commit and notify** — The staged theme moves to `~/.local/state/omarchy/current/theme`, the theme name is recorded, and running shells receive notification.

During activation, the system executes **`theme-set` hooks** from `~/.config/omarchy/hooks/theme-set*` and dispatches *post-theme* commands to restart or retint applications【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L40-L45】.

## Template Rendering and Color Helpers

The heart of how the Omarchy theming system works lies in its template engine. All files ending in `.tpl` under `default/themed/` are processed by `omarchy-theme-set-templates`, which performs placeholder substitution using values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L31-L45】.

### Core Placeholder Syntax

- **`{{ accent }}`** — Direct color value insertion
- **`{{ accent_strip }}`** — Color without leading `#` (e.g., `ff5555`)
- **`{{ accent_rgb }}`** — RGB tuple format (e.g., `255, 85, 85`)

### Advanced Color Operations

**Color mixing** enables subtle variations:

```

{{ mix background foreground 15% }}

```

This blends background and foreground colors by 15%, useful for hover states or subtle borders.

**Gradient generation** provides environment-specific outputs:

- **`{{ hypr_gradient hyprland_active_border accent }}`** — Emits a Lua table for Hyprland configuration
- **`{{ shell_gradient ... }}`** — Produces shell-compatible gradient tokens【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L58-L71】

### Template Precedence Rules

Rendered templates populate concrete files like [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml), [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua), and `btop.theme`. However, **hand-written files always win**: if a theme includes a custom [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua), these replace the generated versions【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L31-L35】.

Users can apply system-wide customizations through **`~/.config/omarchy/themed/*.tpl`** — these process before built-in templates, allowing per-user tweaks without modifying core files【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L36-L38】.

## Security and File Filtering

When themes install from Git repositories, Omarchy applies strict security filtering. The `bin/omarchy-theme-set` script contains an `INSTALLED_THEME_DENIED` constant listing forbidden file patterns【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L60-L62】.

Blocked file types include:

- `*.lua` files (executable code)
- Terminal configuration files
- VS Code extensions

This filtering prevents untrusted themes from executing arbitrary code while still allowing visual customization【⁄cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L48-L58】.

## Key Implementation Files

| Component | Path | Purpose |
|-----------|------|---------|
| Theme activator | `bin/omarchy-theme-set` | Staging flow, filtering, hook dispatch |
| Template renderer | `bin/omarchy-theme-set-templates` | Processes `.tpl` files with palette substitution |
| Default templates | `default/themed/*.tpl` | Blueprint configurations for all themed applications |
| Required palette | `themes/<name>/colors.toml` | Central color definitions |
| Example theme | [`themes/solitude/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/solitude/colors.toml) | Reference implementation |
| User templates | `~/.config/omarchy/themed/*.tpl` | Personal template overrides |
| Post-theme hooks | `~/.config/omarchy/hooks/theme-set*` | Custom scripts executed after theme application |

## Practical Examples

### Activating a Theme

```bash
omarchy theme set solitude

```

This executes `bin/omarchy-theme-set solitude`, complete with staging, template rendering, and state updates under `~/.local/state/omarchy/current/`.

### Creating a Custom Palette

```toml

# ~/.config/omarchy/themes/my-theme/colors.toml

mode = "dark"
accent = "#ff5555"
background = "#282a36"
foreground = "#f8f8f2"

```

Run `omarchy theme set my-theme` to apply these colors across your desktop.

### Overriding Generated Configuration

```toml

# ~/.config/omarchy/themes/my-theme/shell.toml

[notifications]
border = "#ff5555"
border-alpha = 0.7

```

This hand-written file supersedes the template-generated version, enabling surgical customization.

### Template Placeholder Usage

Inside `default/themed/shell.toml.tpl`:

```toml
[notifications]
border = "{{ accent }}"
border-alpha = 0.85

```

With `accent = "#ff5555"` in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), the rendered [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) receives the resolved color value directly.

## Summary

- **Theme locations**: System themes live in `/usr/share/omarchy/themes/`, user overrides in `~/.config/omarchy/themes/`
- **Activation command**: `omarchy-theme-set <name>` stages, filters, renders, and commits themes atomically
- **Template engine**: `.tpl` files transform into configs via `omarchy-theme-set-templates` using [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) values
- **Color helpers**: Advanced functions support RGB conversion, hex stripping, mixing, and gradient generation
- **Security model**: Git-installed themes undergo file filtering to block executable content
- **Override precedence**: User templates → theme hand-written files → generated templates

## Frequently Asked Questions

### What files are required to create a working Omarchy theme?

A minimal theme requires only **[`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)** with valid color definitions. Optional files like [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml), [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua), or background images extend functionality but aren't mandatory. If [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) is missing, Omarchy can generate one from an existing [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) file during activation.

### How do I customize a theme without losing changes on updates?

Place overrides in **`~/.config/omarchy/themes/<name>/`** rather than modifying system files. For template-level changes, add `*.tpl` files to `~/.config/omarchy/themed/` — these process before built-in templates. Hand-written configuration files in your user theme directory always supersede generated versions.

### Why are some files missing after installing a theme from Git?

Omarchy's security filter removes potentially dangerous files from Git-installed themes. The `INSTALLED_THEME_DENIED` list in `bin/omarchy-theme-set` blocks `*.lua` files, terminal configs, and VS Code extensions. This prevents malicious themes from executing code while preserving visual customization capabilities.

### What hooks are available during theme activation?

The **`theme-set` hook** fires during activation — place executable scripts matching `~/.config/omarchy/hooks/theme-set*` to run custom code. The system also dispatches post-theme commands that handle application restarts and retinting automatically, no manual configuration needed for supported applications.