# How to Override Theme Colors in Omarchy: Complete Customization Guide

> Override Omarchy theme colors by creating a user theme directory and editing colors.toml. Customize your Omarchy experience with complete control over your application's look and feel.

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

---

**Override Omarchy theme colors by creating a user-level theme directory in `~/.config/omarchy/themes/<name>/` and editing its [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file, which automatically shadows the built-in system theme.**

Omarchy's theming system uses a **layered override architecture** that lets you modify any color palette without touching system files. This guide explains how to leverage the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) format and user-level theme directories to customize your desktop appearance, based on the source implementation in `omac/omarchy`.

## Understanding Omarchy's Theme Architecture

Omarchy stores themes in two locations with a clear precedence hierarchy:

| Location | Purpose |
|----------|---------|
| `/usr/share/omarchy/themes/<name>/` | Built-in themes shipped with the system (source tree under `themes/`) |
| `~/.config/omarchy/themes/<name>/` | User-provided or customized themes that override system defaults |

Each theme directory contains a **[`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)** file that defines the complete palette: `background`, `foreground`, `accent`, and the 16 ANSI colors (`color0` through `color15`). When you run `omarchy theme set <name>`, the system first checks the user directory; if a matching theme exists there, it loads that [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), otherwise it falls back to the system location according to [`manual/06-themes.md`](https://github.com/omacom/omarchy/blob/main/manual/06-themes.md).

## Method 1: Override Colors via User-Level [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)

This is the primary method for **how to override theme colors in Omarchy**. Follow these steps:

1. **Create the user theme directory** matching your target theme name:

```bash
mkdir -p ~/.config/omarchy/themes/nord

```

2. **Copy the original [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)** from the system location:

```bash
cp /usr/share/omarchy/themes/nord/colors.toml ~/.config/omarchy/themes/nord/

```

3. **Edit the color values** in your copied file. The TOML structure uses standard hex color notation:

```toml

# Example ~/.config/omarchy/themes/nord/colors.toml

background = "#2e3440"
foreground = "#d8dee9"
accent = "#88c0d0"  # Changed from original #81a1c1

color0 = "#3b4252"

# ... color1 through color15

```

4. **Apply the modified theme**:

```bash
omarchy theme set nord

```

The change takes effect immediately across the desktop, terminal, and status bar. The original system theme remains untouched.

## Method 2: Template-Based Color Overrides

For application-specific color mapping, Omarchy supports **template files** in `~/.config/omarchy/themed/`. These let you control how color variables convert into program-specific formats.

Copy and customize the sample template:

```bash
cp ~/.config/omarchy/themed/alacritty.toml.tpl.sample \
   ~/.config/omarchy/themed/alacritty.toml.tpl

```

Templates support variable modifiers like `_strip` and `_rgb` for raw value extraction. The next theme application regenerates the final configuration file. This mechanism is documented in [`manual/43-making-your-own-theme.md`](https://github.com/omacom/omarchy/blob/main/manual/43-making-your-own-theme.md).

## Legacy Theme Support

Themes predating the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) format are handled through backward compatibility. As verified in [`test/shell.d/theme-staging-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/theme-staging-test.sh), Omarchy synthesizes a palette from the theme's existing [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) when [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) is absent. To override legacy themes, create the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file explicitly in your user directory—the presence of this file takes precedence over legacy detection.

## Quick Theme Switching

Toggle between palettes using the CLI or keyboard shortcut:

```bash

# Switch to your customized nord theme

omarchy theme set nord

# Switch to a different preset

omarchy theme set catppuccin

```

Keyboard shortcut: `Super + Ctrl + Shift + Space` opens the theme menu directly.

## Key Source Files and Their Roles

- [`manual/06-themes.md`](https://github.com/omacom/omarchy/blob/main/manual/06-themes.md) — User guide for theme selection and directory structure
- [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md) — Technical documentation of loading order and precedence
- [`test/shell.d/theme-staging-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/theme-staging-test.sh) — Automated test confirming user overlay override behavior
- [`default/agents/skills/omarchy/theming.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/theming.md) — Internal skill driving `omarchy theme` commands
- `themes/<name>/colors.toml` — Built-in theme palettes (system location)
- `~/.config/omarchy/themes/<name>/colors.toml` — Your override files (user location)

## Summary

- **User directories shadow system themes**: Place files in `~/.config/omarchy/themes/<name>/` to override without modifying system files.
- **[`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) is the single source of truth**: Edit `background`, `foreground`, `accent`, and ANSI colors in this TOML file.
- **Templates enable per-app customization**: Use `~/.config/omarchy/themed/*.tpl` files to control color variable mapping.
- **Apply with `omarchy theme set <name>`**: Changes propagate instantly across the desktop environment.
- **System themes remain pristine**: Your modifications live only in user space for easy backup and versioning.

## Frequently Asked Questions

### What file format does Omarchy use for theme colors?

Omarchy uses **TOML** for color definitions in a file named [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml). Colors are specified as hex strings (e.g., `"#2e3440"`). The file supports standard keys: `background`, `foreground`, `accent`, and indexed ANSI colors `color0` through `color15`.

### Can I override just one color without copying the entire file?

No—Omarchy's override mechanism works at the directory level, not the individual key level. You must provide a complete [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) in your user theme directory. Copy the original from `/usr/share/omarchy/themes/<name>/colors.toml` and modify only the values you need changed.

### Where do my custom theme changes persist across upgrades?

All user modifications belong in `~/.config/omarchy/themes/` and `~/.config/omarchy/themed/`. These directories are never modified by system updates. The separation of user and system paths (`/usr/share/omarchy/themes/`) ensures your customizations survive indefinitely.

### How do I verify my override is being loaded?

Run `omarchy theme set <name>` with verbose output or check the generated configuration files in `~/.config/omarchy/current/`. The staging test in [`test/shell.d/theme-staging-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/theme-staging-test.sh) demonstrates the validation approach: user-level [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) files take unconditional precedence over system equivalents when present.