Where Are Omarchy Themes Stored and How They Work: Complete Guide

Omarchy themes are stored in two locations—stock themes reside in /usr/share/omarchy/themes/ while custom user themes live in ~/.config/omarchy/themes/, with both directories merged at runtime to allow seamless customization without modifying system files.

Managing visual customization in the Omarchy desktop environment requires understanding exactly where theme files reside and how the system prioritizes them. Based on the source code from the basecamp/omarchy repository, themes are organized in a hierarchical overlay system that separates system defaults from user modifications. This guide examines the complete file structure, configuration formats, and CLI commands that control Omarchy theming.

Theme Storage Locations and Directory Structure

Omarchy employs a dual-path storage strategy that distinguishes between immutable stock themes and mutable user customizations. According to the theming documentation in quattro/docs/theming.md, the system scans both directories at runtime and presents a unified list to the user.

Stock Themes in /usr/share/omarchy/themes/

Stock themes ship with the Omarchy repository and are installed system-wide. During installation, the contents of the repository's themes/ directory are copied to /usr/share/omarchy/themes/<name>/. These directories serve as read-only reference implementations that define the default visual appearance of the desktop environment.

Each stock theme directory contains at minimum a colors.toml file defining the color palette, and may include additional configuration files like shell.toml or hyprland.lua that specify UI surface roles and window sizing parameters.

User-Installed Custom Themes in ~/.config/omarchy/themes/

User themes reside in ~/.config/omarchy/themes/<name>/ and follow the same internal structure as stock themes. This location allows users to create custom color schemes without requiring root privileges or modifying system files. The overlay system ensures that when a user selects a custom theme name matching a stock theme, the user version takes precedence.

As documented in manual/43-making-your-own-theme.md, creating a custom theme typically involves copying a stock theme from /usr/share/omarchy/themes/ into the user directory, then editing the constituent files to modify colors and layout properties.

Theme File Structure and Configuration Files

Individual themes are not single files but directories containing specific TOML and Lua configuration files. The Omarchy theme engine parses these files to construct the complete visual environment, affecting everything from the top bar to terminal applications.

colors.toml Palette Definition

The colors.toml file serves as the primary palette definition, specifying accent colors, background values, foreground text colors, and semantic color roles. This file is mandatory for every theme and uses a straightforward key-value structure that the system reads during theme initialization.

shell.toml and hyprland.lua UI Configuration

Beyond color definitions, themes may include shell.toml or alternatively hyprland.lua to define UI surface roles, window sizing, spacing parameters, and layout-specific overrides. These files control the structural presentation of Omarchy interface elements, including the top bar dimensions, splash screen positioning, and terminal-side application layouts.

How to List, Apply, and Create Omarchy Themes

The Omarchy CLI provides unified access to both stock and user themes, automatically merging the two storage locations into a single selectable inventory.

List available themes from both locations:

omarchy theme list

Apply a theme by name:

omarchy theme set catppuccin

Create a custom theme by copying a stock reference and editing the configuration:

mkdir -p ~/.config/omarchy/themes/my-custom
cp /usr/share/omarchy/themes/catppuccin/colors.toml ~/.config/omarchy/themes/my-custom/

# Edit ~/.config/omarchy/themes/my-custom/colors.toml as desired

omarchy theme set my-custom

Verify the storage locations directly:

ls /usr/share/omarchy/themes    # Stock themes

ls ~/.config/omarchy/themes       # User themes

The theme selector interface, accessible via Super + Ctrl + Shift + Space, draws from these configuration files to restyle the entire UI hierarchy dynamically.

Summary

• Omarchy themes exist in two distinct tiers: system stock themes under /usr/share/omarchy/themes/ and user customizations in ~/.config/omarchy/themes/.
• Every theme directory requires at minimum a colors.toml file to define the color palette.
• Advanced theming utilizes shell.toml or hyprland.lua for UI surface roles and sizing adjustments.
• The omarchy CLI command automatically merges both storage locations, allowing seamless switching between stock and custom themes without file path concerns.
• User themes override stock themes of the same name, enabling safe customization workflows that preserve system defaults.

Frequently Asked Questions

Where are Omarchy themes stored by default?

Stock themes are installed to /usr/share/omarchy/themes/<name>/ during system installation, while user-created or modified themes reside in ~/.config/omarchy/themes/<name>/. The Omarchy CLI reads both locations simultaneously and presents them as a unified list when running omarchy theme list.

What files are required to create a custom Omarchy theme?

A valid Omarchy theme requires at minimum a colors.toml file containing palette definitions for accent, background, and foreground colors. Optional files include shell.toml or hyprland.lua for defining UI surface roles, window sizing, and layout-specific configurations that control the appearance of the top bar and splash screen.

How do I switch between themes in Omarchy?

Use the command-line interface with omarchy theme set <theme-name> to apply any available theme immediately. Alternatively, press Super + Ctrl + Shift + Space to open the graphical theme selector, which parses the colors.toml and shell.toml files from both stock and user directories to restyle the desktop environment.

Can I override stock themes without modifying system files?

Yes. Copy any stock theme from /usr/share/omarchy/themes/<name>/ to ~/.config/omarchy/themes/<name>/ and modify the files there. The user directory takes precedence in the overlay system, meaning your custom version will override the stock theme when selected, leaving the original system files untouched.

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