# How to Create a Custom Omarchy Theme: A Complete Step-by-Step Guide

> Learn how to create a custom Omarchy theme by building a color palette and overriding templates. This step-by-step guide makes customizing your Omarchy experience easy and efficient.

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

---

**Creating a custom Omarchy theme requires building a palette in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), optionally adding template overrides, and applying it with `omarchy-theme-set <name>`.**

Omarchy's theming system is built on two foundational components: a **semantic color palette** defined in [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and a set of **templates** that transform that palette into concrete configuration files for your shell, Hyprland, terminals, editors, and other applications. This architecture separates aesthetic decisions from implementation details, allowing you to change your entire desktop appearance by editing a single file. According to the Omarchy source code, the theming workflow creates a staging directory, copies the base theme, overlays any user-provided overrides, generates files from templates, and installs the result into `~/.local/state/omarchy/current/theme`【/cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L18-L30】.

## Where Custom Omarchy Themes Live

Omarchy discovers themes in two locations. Understanding these paths is essential before you begin creating your custom Omarchy theme.

- **System themes**: `/usr/share/omarchy/themes/<name>/` — first-party themes shipped with Omarchy
- **Personal themes**: `~/.config/omarchy/themes/<name>/` — themes you create and maintain yourself【/cache/repos/github.com/omacom/omarchy/quattro/manual/43-making-your-own-theme.md#L1-L4】

The personal directory is where you will build your custom creation. Omarchy prioritizes user themes over system themes when names collide.

## The Core of Every Omarchy Theme: [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)

The [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file defines a **semantic palette** — abstract color names that templates reference rather than hardcoded values. This enables consistent theming across dozens of applications.

Typical palette keys include `accent`, `background`, `foreground`, `red`, `green`, `blue`, and more. Templates consume these through placeholders like `{{ accent }}` or advanced expressions such as `{{ mix background foreground 15% }}` to generate derived colors【/cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L68-L46】.

Add `mode = "light"` to create a light-mode variant, or keep the default dark mode by omitting this key or setting `mode = "dark"`【/cache/repos/github.com/omacom/omarchy/quattro/manual/43-making-your-own-theme.md#L19-L22】.

## Security Boundaries: What Files Survive Installation

When you create a custom Omarchy theme, you must understand Omarchy's security model for installed themes versus manually created ones.

- **Non-executable files** ([`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml), `icons.theme`, `backgrounds/`, images) are copied verbatim in all themes
- **Executable content** (`.lua` scripts, terminal configs, [`vscode.json`](https://github.com/omacom/omarchy/blob/main/vscode.json)) is **stripped from git-cloned themes** to prevent supply-chain attacks
- **Executable content is preserved** only in themes you create manually in `~/.config/omarchy/themes/`【/cache/repos/github.com/omacom/omarchy/quattro/manual/43-making-your-own-theme.md#L11-L15】

This distinction matters if you plan to distribute your theme. For maximum portability, rely on the palette and template system rather than custom scripts.

## Step-by-Step: Building Your Custom Omarchy Theme

Follow this proven workflow to create, customize, and activate your theme.

### Step 1: Bootstrap From an Existing Theme

Copy a system theme as your starting point. The `aurora` theme provides a well-structured foundation.

```bash
mkdir -p ~/.config/omarchy/themes/my-theme
cp -r /usr/share/omarchy/themes/aurora/* ~/.config/omarchy/themes/my-theme/

```

### Step 2: Define Your Palette

Edit [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) with your preferred colors. This is the single most important file in your custom Omarchy theme.

```bash
$EDITOR ~/.config/omarchy/themes/my-theme/colors.toml

```

Example configuration:

```toml
mode = "dark"
accent = "#ff6e6b"
background = "#1e1e2e"
foreground = "#c0caf5"
red = "#f38ba8"
green = "#a6e3a1"
blue = "#89b4fa"
yellow = "#f9e2af"
magenta = "#cba6f7"
cyan = "#89dceb"

```

### Step 3: Add Selective Overrides (Optional)

Rather than editing generated files directly, provide overrides that Omarchy applies after template rendering.

**Full override**: Replace an entire generated file.

```bash

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

cat > ~/.config/omarchy/themes/my-theme/shell.toml <<'EOF'
[interface]
prompt = "❯ "
prompt_color = "accent"
EOF

```

**Partial override**: Replace only a specific section using the `.<section>` suffix.

```bash

# ~/.config/omarchy/themes/my-theme/shell.lock.toml — affects only [lock] section

cat > ~/.config/omarchy/themes/my-theme/shell.lock.toml <<'EOF'
[lock]
text = "#ffffff"
placeholder = "#aaaaaa"
border = "#ff6e6b"
EOF

```

The lock file pattern [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) merges only the `[lock]` section into the final shell configuration【/cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L78-L88】.

### Step 4: Create Custom Templates (Optional)

For applications not yet supported by Omarchy's built-in templates, add user-wide custom templates to `~/.config/omarchy/themed/`.

```bash
mkdir -p ~/.config/omarchy/themed
cat > ~/.config/omarchy/themed/myapp.conf.tpl <<'EOF'

# My custom app configuration

primary_color = {{ accent | strip_quotes }}
bg_color = {{ background | strip_quotes }}
EOF

```

Files in this directory with the `.tpl` extension are processed for every theme you apply【/cache/repos/github.com/omacom/omarchy/quattro/manual/43-making-your-own-theme.md#L32-L36】.

### Step 5: Generate and Apply Your Theme

Run the theme installation command to stage, render templates, and activate your custom Omarchy theme.

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

```

This command notifies the running shell to refresh its configuration, and regenerates all dependent application configs including Hyprland, terminal emulators, and status bars【/cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L20-L28】.

### Step 6: Verify with the Theme Preview Tool

Before committing to your design, validate that all placeholders resolve correctly and inspect your color ramp.

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

```

The preview displays your complete palette with resolved color values, helping you catch template errors or missing palette keys【/cache/repos/github.com/omacom/omarchy/quattro/docs/theming.md#L28-L30】.

## Publishing Your Custom Omarchy Theme

To share your creation with others, initialize a Git repository and push to a public host. The Omarchy community prefers the naming convention `omarchy-<name>-theme`.

```bash
cd ~/.config/omarchy/themes/my-theme
git init
git add .
git commit -m "Initial theme: my-theme"
git remote add origin https://github.com/yourname/omarchy-my-theme.git
git push -u origin master

```

Users install published themes with a single command:

```bash
omarchy theme install https://github.com/yourname/omarchy-my-theme.git

```

This workflow automatically clones the repository, validates the structure, and makes the theme available for `omarchy-theme-set`【/cache/repos/github.com/omacom/omarchy/quattro/manual/43-making-your-own-theme.md#L37-L41】.

## Key Files in Every Custom Omarchy Theme

| File | Purpose | Location |
|------|---------|----------|
| [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) | Semantic palette definition | `themes/<name>/colors.toml` |
| [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) | Full shell configuration override | `themes/<name>/shell.toml` |
| `shell.<section>.toml` | Partial shell configuration override | `themes/<name>/shell.lock.toml` |
| `icons.theme` | Icon set selection for file managers | `themes/<name>/icons.theme` |
| `backgrounds/` | Wallpaper and background images | `themes/<name>/backgrounds/` |
| `unlock.png` | Custom unlock screen image (transparent PNG recommended) | `themes/<name>/unlock.png` |
| `*.tpl` (user-wide) | Custom templates for additional apps | `~/.config/omarchy/themed/*.tpl` |

Built-in templates shipped with Omarchy live in `default/themed/*.tpl` and demonstrate the full template syntax including color mixing, conditional logic, and filter pipelines.

## Summary

- **Custom Omarchy themes** live in `~/.config/omarchy/themes/<name>/` and are applied with `omarchy-theme-set <name>`
- **[`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)** is the heart of every theme, defining a semantic palette consumed by templates
- **Overrides** use [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) for full replacement or [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) for partial section replacement
- **Security boundaries** strip executable content from installed themes but preserve it in manually created themes
- **Preview your work** with `omarchy dev theme-preview <name>` before finalizing
- **Distribute themes** via Git repositories using the `omarchy-<name>-theme` naming convention

## Frequently Asked Questions

### How do I switch between light and dark variants in my custom Omarchy theme?

Set `mode = "light"` or `mode = "dark"` in your [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file. Omarchy's templates use this key to adjust contrast ratios, border colors, and selection highlights appropriately. Some templates include conditional logic that renders different values based on the mode setting.

### Why are my `.lua` scripts missing after others install my theme?

Omarchy's security model strips executable files — including `.lua`, shell scripts, and JSON configs with code — from themes installed via `omarchy theme install`. Only manually created themes in `~/.config/omarchy/themes/` preserve these files. Design your theme to rely on the palette and template system for maximum portability.

### Can I override colors for just one application without affecting others?

Yes. Use partial override files like [`shell.lock.toml`](https://github.com/omacom/omarchy/blob/main/shell.lock.toml) to target specific sections, or place application-specific templates in `~/.config/omarchy/themed/` with precise naming. The template engine processes user-wide templates alongside theme-specific ones, allowing surgical customization without forking the entire theme.