How to Create a Custom Omarchy Theme: A Complete Guide

Create a custom Omarchy theme by copying an existing theme to ~/.config/omarchy/themes/<name>/, editing colors.toml to define your palette, optionally adding override files or custom templates, and running omarchy-theme-set <name> to apply it.

Omarchy's theming system is built on two core concepts: a semantic color palette defined in colors.toml and template files that transform that palette into concrete configuration files for the shell, Hyprland, terminals, editors, and other applications. This guide walks through creating a custom Omarchy theme based on the actual implementation in the omacom/omarchy repository.

Where Custom Themes Live

Omarchy looks for themes in two locations:

• System themes: /usr/share/omarchy/themes/<name>/ (first-party themes shipped with Omarchy)
• User themes: ~/.config/omarchy/themes/<name>/ (personal themes you create)

Place your custom work in the user directory to ensure it persists across system updates.

The Core File: colors.toml

Every theme requires a colors.toml file that defines the semantic palette. This file uses simple key-value pairs that templates reference as placeholders like {{ accent }} or {{ mix background foreground 15% }}.

Create or edit this file at ~/.config/omarchy/themes/<name>/colors.toml:

mkdir -p ~/.config/omarchy/themes/my-theme
cp -r /usr/share/omarchy/themes/aurora/* ~/.config/omarchy/themes/my-theme/
$EDITOR ~/.config/omarchy/themes/my-theme/colors.toml

Example colors.toml contents:

mode = "dark"          # or "light"

accent = "#ff6e6b"
background = "#1e1e2e"
foreground = "#c0caf5"
red = "#f38ba8"
green = "#a6e3a1"
blue = "#89b4fa"

The mode key signals light versus dark mode to applications that respect it. All other keys are arbitrary—templates reference whatever you define.

How Themes Are Built

When you run omarchy-theme-set <name>, the command executes a multi-stage process as implemented in the Omarchy source:

1. Creates a staging directory
2. Copies the base theme files
3. Overlays any user-provided overrides
4. Renders templates using the palette values
5. Installs the result to ~/.local/state/omarchy/current/theme
6. Notifies the running shell to reload configurations

Templates live in default/themed/*.tpl within the Omarchy installation and use Tera-style syntax with Omarchy-specific helpers for color mixing and manipulation.

Adding Override Files

You can override generated configurations without editing templates. Omarchy distinguishes between two override types:

Full-File Overrides

Place a complete configuration file in your theme directory to replace the generated version entirely:

# Replace the entire shell configuration

cat > ~/.config/omarchy/themes/my-theme/shell.toml <<'EOF'
[general]
font = "JetBrainsMono Nerd Font"
font_size = 11

[colors]
background = "#1e1e2e"
foreground = "#c0caf5"
EOF

Partial Section Overrides

Use .<section> in the filename to replace only a specific section of a generated file:

# Replace only the [lock] section of shell.toml

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

This pattern works for any TOML-based configuration that Omarchy generates.

Custom Templates for Unsupported Apps

To theme applications not covered by Omarchy's built-in templates, add user-wide custom templates:

1. Create the directory: mkdir -p ~/.config/omarchy/themed/
2. Write a template file with .tpl extension, e.g., myapp.conf.tpl
3. Reference palette keys with {{ variable_name }} syntax

# Example: ~/.config/omarchy/themed/alacritty.yml.tpl

cat > ~/.config/omarchy/themed/alacritty.yml.tpl <<'EOF'
colors:
  primary:
    background: '{{ background }}'
    foreground: '{{ foreground }}'
  normal:
    black:   '{{ background }}'
    red:     '{{ red }}'
    green:   '{{ green }}'
    blue:    '{{ blue }}'
EOF

These templates render alongside built-ins when you apply your theme.

Security Note on Code Execution

Omarchy applies different trust levels based on theme origin:

• Manually created themes (in ~/.config/omarchy/themes/): All files preserved, including executable code
• Installed/git-cloned themes: Files that could execute—.lua scripts, terminal configs, vscode.json—are stripped for security

Non-executable files like shell.toml, icons.theme, and backgrounds/ directories copy verbatim regardless of origin.

Previewing and Applying Your Theme

Apply your theme and preview the results:

# Apply the theme

omarchy-theme-set my-theme

# Preview the color ramp and verify placeholder resolution

omarchy dev theme-preview my-theme

The theme-preview command renders the theme in a staging directory without installing it, showing you exactly how palette values expand across all generated files.

Sharing Your Theme

To distribute your theme, publish it as a Git repository following the naming convention omarchy-<name>-theme:

cd ~/.config/omarchy/themes/my-theme
git init
git add .
git commit -m "Initial My Theme release"
git remote add origin https://github.com/yourname/omarchy-my-theme.git
git push -u origin main

Users install it with:

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

Complete Theme File Structure

A fully-featured custom Omarchy theme may include:

File	Purpose
colors.toml	Semantic palette definition (required)
shell.toml	Full shell config override
shell.<section>.toml	Partial shell config override
icons.theme	Icon theme selection for file managers
backgrounds/	Wallpaper images
unlock.png	Custom unlock screen image (transparent PNG recommended)
*.toml (other)	Overrides for other generated configs

Summary

• Create a custom Omarchy theme in ~/.config/omarchy/themes/<name>/ by copying an existing theme
• Define your palette in colors.toml with semantic color keys and optional mode = "light" or "dark"
• Override specific configurations with full files (e.g., shell.toml) or partial sections (e.g., shell.lock.toml)
• Extend support to new applications by adding custom .tpl templates to ~/.config/omarchy/themed/
• Apply with omarchy-theme-set <name> and preview with omarchy dev theme-preview <name>
• Share by pushing to a Git repository and instructing users to run omarchy theme install <url>

Frequently Asked Questions

What is the minimum required structure for a workable Omarchy theme?

A valid Omarchy theme requires only colors.toml in the theme directory. All other files are generated from templates using the palette values defined there. You can add override files or custom templates as needed, but the palette alone is sufficient for a functional theme.

Can I override just one color value without replacing an entire file?

Yes. Create a partial override file using the filename.section.toml naming pattern. For example, shell.prompt.toml replaces only the [prompt] section of the generated shell configuration while preserving all other sections.

Why are some files missing when I install a theme from Git?

Omarchy's theme install command strips potentially executable files—.lua scripts, terminal configurations, vscode.json, and similar—as a security measure. This applies only to git-cloned themes. Files you create manually in ~/.config/omarchy/themes/ are preserved unconditionally.

Do light mode themes require different templates?

No. Templates handle light versus dark mode automatically. Set mode = "light" in your colors.toml and use the same template files. Applications that respect the mode setting will adapt accordingly; those that don't will use your literal palette values.

How do I add support for an application Omarchy doesn't theme yet?

Create a custom template in ~/.config/omarchy/themed/ with a .tpl extension and the exact filename you want generated. Reference palette keys with {{ variable_name }} syntax. Run omarchy-theme-set to render it alongside built-in templates.

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