How to Create a Custom Omarchy Theme: Complete Guide for Beginners

Creating a custom Omarchy theme requires placing a colors.toml file inside ~/.config/omarchy/themes/<name>/ and running omarchy theme set <name> to generate the full configuration from templates.

Omarchy is an opinionated Linux desktop environment developed by Basecamp that uses a simple file-based theming system. Building a custom Omarchy theme lets you define color palettes, UI overrides, and asset collections that the system compiles into active configurations. This guide walks through the exact file structure, required syntax, and activation process based on the current basecamp/omarchy source code.

Where Omarchy Looks for Themes

The theming system searches for theme definitions in two distinct locations before building the active configuration.

Stock Themes (System-Wide)

Omarchy ships with pre-built themes stored in /usr/share/omarchy/themes/<name>/. In the source repository, these live under the themes/ directory and include examples like solitude, retro-82, and lumon. These serve as base templates that you can extend or override rather than modify directly.

User Custom Themes (Local Configuration)

Personal themes belong in ~/.config/omarchy/themes/<name>/. When you run omarchy theme set <name>, the command prioritizes files in this user directory, overlaying them on top of any stock theme with the same name. According to docs/theming.md, the system copies stock files first, then overlays your custom files, ensuring your modifications take precedence without destroying the base template.

The Required colors.toml Structure

Every custom Omarchy theme must contain a colors.toml file at its root. This file supplies the palette keys used by built-in templates to generate application-specific configs.

The TOML file requires at minimum these keys:

mode = "dark"  # or "light"

accent = "#ff6f61"
selection = "#2c2c2c"
muted = "#44475a"

background = "#1e1e2e"
dark_background = "#14141a"
lighter_background = "#282a36"

foreground = "#f8f8f2"
bright_foreground = "#ffffff"

red = "#ff5555"
green = "#50fa7b"
blue = "#6272a4"

As documented in docs/theming.md lines 46-71, these values drive the template engine that produces shell.toml, terminal configs, and window manager styles.

Optional Overrides and Assets

Beyond the color palette, you can supply complete file replacements or additional assets that Omarchy copies verbatim during installation.

Configuration Overrides

Place files with specific names in your theme directory to replace generated defaults:

• shell.toml – Replaces the entire shell color configuration.
• shell.lock.toml – Replaces only the [lock] section of the shell config (the filename determines the target section).
• hyprland.lua – Overrides the generated Hyprland window manager configuration.

According to docs/theming.md lines 56-66, the staging process checks for these exact filenames and copies them instead of running the template generator.

Asset Files

You can include static resources that Omarchy installs alongside configs:

• backgrounds/ – Directory containing wallpaper images.
• preview.png – Thumbnail image displayed in theme selectors.
• icons.theme – Custom icon theme definitions.

These files live in your theme directory and copy directly to ~/.local/state/omarchy/current/theme during activation.

Activating Your Custom Theme

Once your files are in place, use the CLI driver to build and install the theme:

omarchy theme set my-theme

This command executes the logic found in bin/omarchy-theme-set (inspectable via cat $(which omarchy-theme-set)). The process follows these steps:

1. Creates a staging directory.
2. Copies the stock theme (if it exists) into the staging area.
3. Overlays files from ~/.config/omarchy/themes/<name>/.
4. Generates missing template files (like shell.toml from colors.toml).
5. Installs the final result to ~/.local/state/omarchy/current/theme.
6. Signals the running shell to reload the new colors.

The change applies immediately without requiring a logout or reboot.

Complete Example: Building a Solarflare Theme

Here is a runnable workflow to create and activate a custom theme named "solarflare":

# 1. Create the theme directory

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

# 2. Write the base palette

cat > ~/.config/omarchy/themes/solarflare/colors.toml <<'EOF'
mode = "dark"

accent = "#ffb86c"
selection = "#44475a"
muted = "#6272a4"

background = "#1e1e2e"
foreground = "#f8f8f2"

red = "#ff5555"
green = "#50fa7b"
blue = "#8be9fd"
EOF

# 3. (Optional) Provide a custom shell palette

cat > ~/.config/omarchy/themes/solarflare/shell.toml <<'EOF'
[bar]
background = "{{ background }}"
foreground = "{{ foreground }}"
accent = "{{ accent }}"
EOF

# 4. (Optional) Add a background asset

mkdir -p ~/.config/omarchy/themes/solarflare/backgrounds
cp ~/wallpaper.png ~/.config/omarchy/themes/solarflare/backgrounds/

# 5. Activate the theme

omarchy theme set solarflare

Summary

• Location: Place custom themes in ~/.config/omarchy/themes/<name>/ to override stock themes stored in /usr/share/omarchy/themes/.
• Requirement: Every theme needs a colors.toml file defining the palette keys (accent, background, foreground, etc.).
• Overrides: Add files like shell.toml or hyprland.lua to replace generated configurations entirely.
• Activation: Run omarchy theme set <name> to stage, generate, and install the theme to ~/.local/state/omarchy/current/theme.

Frequently Asked Questions

Where do I place files for a custom Omarchy theme?

User-created themes belong in ~/.config/omarchy/themes/<name>/. This directory takes precedence over system stock themes located in /usr/share/omarchy/themes/, allowing your custom files to override default configurations without modifying system packages.

What is the minimum file needed for a custom Omarchy theme?

You only need a colors.toml file containing the palette definition. The omarchy theme set command uses this file to generate all other necessary configuration files via templates, though you can optionally supply pre-generated files to override specific outputs.

Can I override specific sections of generated configs rather than entire files?

Yes. Use dot-notation filenames like shell.lock.toml to target specific TOML sections. According to the theming documentation in docs/theming.md, the filename determines which section of the generated config gets replaced, letting you override just the [lock] section while keeping other generated values intact.

How does Omarchy handle missing files in a custom theme?

Missing files are generated automatically from templates during the staging process. The system copies your provided files first, then runs the template engine to create any missing configs (like shell.toml or hyprland.lua) using the colors.toml palette values, ensuring a complete theme installation even with partial user input.

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