How to Override Theme Colors in Omarchy: Complete Customization Guide

Override Omarchy theme colors by creating a user-level theme directory in ~/.config/omarchy/themes/<name>/ and editing its 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 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 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, otherwise it falls back to the system location according to manual/06-themes.md.

Method 1: Override Colors via User-Level 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:

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

2. Copy the original colors.toml from the system location:

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:

# 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:

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:

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.

Legacy Theme Support

Themes predating the colors.toml format are handled through backward compatibility. As verified in test/shell.d/theme-staging-test.sh, Omarchy synthesizes a palette from the theme's existing alacritty.toml when colors.toml is absent. To override legacy themes, create the 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:

# 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 — User guide for theme selection and directory structure
• docs/theming.md — Technical documentation of loading order and precedence
• test/shell.d/theme-staging-test.sh — Automated test confirming user overlay override behavior
• 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 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. 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 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 demonstrates the validation approach: user-level colors.toml files take unconditional precedence over system equivalents when present.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}