# How to Create a New Theme for Omarchy Using colors.toml

> Learn how to create a new Omarchy theme by defining a colors.toml file in your config directory and activating it with a simple command for custom system-wide palettes.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Create a new Omarchy theme by placing a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file in `~/.config/omarchy/themes/<name>/` and running `omarchy-theme-set <name>` to render templates and activate the palette across your system.**

Omarchy—the opinionated Arch Linux distribution from `omacom/omarchy`—uses a centralized color system that eliminates manual editing of downstream configuration files. By defining your palette in a single [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file, you can generate consistent theming for the shell, window manager, and applications without touching individual config syntax.

## Understanding the Omarchy Theme Architecture

Omarchy themes reside in theme-specific directories under `~/.config/omarchy/themes/<name>/`. According to the repository structure documented in [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md), the system relies on a strict separation between palette definitions and generated configurations.

### The colors.toml File

The **only required file** for a functional theme is [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). This TOML file defines semantic color keys that drive all generated configs. As implemented in `omacom/omarchy`, the palette supports standard keys like `accent`, `background`, `foreground`, and named colors (e.g., `red`, `blue`).

A minimal [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) requires these fields:

```toml
mode = "dark"

accent = "#7aa2f7"
selection = "#292e42"
muted = "#414868"

background = "#1a1b26"
dark_background = "#13141c"
darker_background = "#0e0e14"
lighter_background = "#24283b"

foreground = "#a9b1d6"
dark_foreground = "#565f89"
light_foreground = "#b4bee6"
bright_foreground = "#c0caf5"

red = "#f7768e"
blue = "#7aa2f7"

```

*(Reference the full schema in [`themes/nord/colors.toml`](https://github.com/omacom/omarchy/blob/main/themes/nord/colors.toml) within the repository.)*

### Template Rendering System

When you execute `omarchy-theme-set <name>`, the system performs three operations defined in `bin/omarchy-theme-set`:

1. **Staging**: Copies the theme directory to `~/.local/state/omarchy/current/next-theme`
2. **Rendering**: Processes `*.tpl` templates (such as `default/themed/shell.toml.tpl`) using values from [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)
3. **Installation**: Deploys rendered files to `~/.local/state/omarchy/current/theme` and notifies the running shell

Templates reference palette values using three variable formats:
- `{{ key }}` – Raw hex value
- `{{ key_strip }}` – Hex without the `#` prefix
- `{{ key_rgb }}` – RGB format for legacy applications

## Step-by-Step Guide to Create a New Omarchy Theme

### 1. Create the Theme Directory

Initialize your theme folder in the user config directory:

```bash
mkdir -p ~/.config/omarchy/themes/my-theme

```

### 2. Define Your Color Palette

Copy an existing theme as a starter or create [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) manually:

```bash

# Copy Nord theme as a base

cp -r /usr/share/omarchy/themes/nord/* ~/.config/omarchy/themes/my-theme/

# Edit the palette

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

```

Ensure you set `mode = "dark"` or `mode = "light"` at the top of the file. For light themes, you may alternatively place an empty `light.mode` file in the theme directory.

### 3. Preview Your Theme

Validate your color ramp before activation:

```bash
omarchy dev theme-preview my-theme

```

This command displays the gradient from `dark_background` through `darker_background` and sample selection colors, allowing you to verify contrast ratios without applying the theme system-wide.

### 4. Activate and Test

Apply the theme to render all templates and update the runtime environment:

```bash
omarchy-theme-set my-theme

```

The command automatically handles template compilation and signals the shell to reload configurations.

## Optional Theme Assets and Overrides

Beyond [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), you may include supplementary files in your theme directory:

- **`preview.png`** / **`preview-unlock.png`** – Visual thumbnails for the theme switcher interface
- **`icons.theme`** – File manager icon theme association
- **`unlock.png`** – Custom background for the lock screen
- **Manual overrides** – Hand-written configs like [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua) that take precedence over generated templates

Place these files alongside [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) to create a complete, portable theme package.

## Security Considerations for Distributed Themes

When distributing themes via Git repositories (installed via `omarchy theme install <url>`), Omarchy implements security sanitization documented in [`manual/43-making-your-own-theme.md`](https://github.com/omacom/omarchy/blob/main/manual/43-making-your-own-theme.md). The system **drops any code-executing files**—including `*.lua`, terminal configs, and [`vscode.json`](https://github.com/omacom/omarchy/blob/main/vscode.json)—keeping only color-related assets. This prevents arbitrary code execution when users install third-party themes, ensuring that only your [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and static assets propagate to the target system.

## Summary

- Create new themes in `~/.config/omarchy/themes/<name>/` with a mandatory [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file
- Use `omarchy-theme-set <name>` to stage, render templates, and activate the theme
- Reference palette values in templates using `{{ key }}`, `{{ key_strip }}`, or `{{ key_rgb }}` syntax
- Preview color ramps safely with `omarchy dev theme-preview` before system-wide activation
- Include optional assets like `preview.png` or manual override configs for complete theming
- Distributed themes automatically strip executable files to prevent security risks

## Frequently Asked Questions

### What is the minimum required file to create an Omarchy theme?

The only mandatory file is [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). This single file contains the complete color palette that drives all generated configuration files. While you can include optional assets like `preview.png` or manual overrides, Omarchy generates functional configs solely from the TOML palette definition.

### How do I create a light mode theme in Omarchy?

Set `mode = "light"` at the top of your [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file, or place an empty `light.mode` file in the theme directory. The `omarchy-theme-set` command detects these indicators and adjusts template generation accordingly for light-friendly applications and UI components.

### Why does Omarchy delete Lua files when I install themes from Git?

Omarchy strips code-executing files—including `*.lua`, terminal configurations, and [`vscode.json`](https://github.com/omacom/omarchy/blob/main/vscode.json)—from Git-installed themes as a security measure. This prevents malicious repository owners from running arbitrary code on your machine. Only color definitions and static assets survive the installation process.

### Can I override specific configuration files while using colors.toml?

Yes. Place hand-written config files—such as [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua)—in your theme directory alongside [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). When `omarchy-theme-set` runs, these manual overrides take precedence over generated templates, allowing you to customize specific applications while still maintaining centralized color management.