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

Create a new Omarchy theme by placing a 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 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, 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. 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 requires these fields:

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

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

2. Define Your Color Palette

Copy an existing theme as a starter or create colors.toml manually:

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

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:

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, 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 or hyprland.lua that take precedence over generated templates

Place these files alongside 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. The system drops any code-executing files—including *.lua, terminal configs, and vscode.json—keeping only color-related assets. This prevents arbitrary code execution when users install third-party themes, ensuring that only your colors.toml and static assets propagate to the target system.

Summary

• Create new themes in ~/.config/omarchy/themes/<name>/ with a mandatory 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. 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 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—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 or hyprland.lua—in your theme directory alongside 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.

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