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

Creating a custom Omarchy theme requires building a palette in 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 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

The 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, icons.theme, backgrounds/, images) are copied verbatim in all themes
• Executable content (.lua scripts, terminal configs, 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.

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 with your preferred colors. This is the single most important file in your custom Omarchy theme.

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

Example configuration:

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.

# ~/.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.

# ~/.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 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/.

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.

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.

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.

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:

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	Semantic palette definition	themes/<name>/colors.toml
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 is the heart of every theme, defining a semantic palette consumed by templates
• Overrides use shell.toml for full replacement or 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 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 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.

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