Where Are Omarchy Themes Stored? A Complete Guide to Theme Locations and Management

Omarchy themes are stored in two locations: stock themes reside in /usr/share/omarchy/themes/<name>/ while user custom themes live in ~/.config/omarchy/themes/<name>/, with the system merging both directories at runtime to present a unified theme list.

Understanding where Omarchy themes are stored is essential for customizing your desktop environment. According to the basecamp/omarchy source code and documentation, the theming system uses a dual-path approach that separates system-wide stock themes from user-specific customizations.

Stock Theme Location (System-Wide)

Stock themes ship with the Omarchy repository in the themes/ directory at the project root. During installation, these directories are copied to the system-wide location:

/usr/share/omarchy/themes/<name>/

Each stock theme directory contains the configuration files that define the visual appearance. The primary file is colors.toml, which specifies the color palette including accent colors, background, and foreground values. Themes may also include shell.toml or hyprland.lua to define UI surface roles and sizing parameters.

As documented in docs/theming.md, these stock themes provide the base layer that all users can access, with themes like catppuccin serving as reference implementations for the expected file structure.

User Theme Location (Custom Installations)

Custom themes created by individual users are stored in the home directory configuration path:

~/.config/omarchy/themes/<name>/

This location follows the XDG Base Directory specification and allows users to override or extend stock themes without modifying system files. When you create a custom theme, you can copy a stock theme from /usr/share/omarchy/themes/ into this user directory and edit the files directly.

The overlay system automatically detects themes in this location. As noted in the theming documentation, Omarchy merges both the stock and user directories at runtime, presenting a combined list through the CLI and graphical theme selector.

How Omarchy Merges Theme Directories

Omarchy employs a runtime merging strategy that combines both storage locations into a single coherent theme list. When you execute omarchy theme list, the CLI queries both /usr/share/omarchy/themes/ and ~/.config/omarchy/themes/ to display all available options.

The theme selector, accessible via the keyboard shortcut Super + Ctrl + Shift + Space, reads from both locations simultaneously. When you select a theme, the system loads colors.toml for the palette and shell.toml (or hyprland.lua) to restyle the entire UI, including the top bar, splash screen, and terminal-side applications.

This design allows users to customize stock themes by copying them to the user directory and modifying specific values, while keeping the originals intact.

Key Theme Files and Structure

Every Omarchy theme requires specific configuration files to function properly:

• colors.toml – Defines the complete color palette including accent colors, background, foreground, and semantic color roles
• shell.toml or hyprland.lua – Configures UI surface roles, window sizing, and layout-specific overrides

Located at themes/<name>/colors.toml in the repository, the color definition file uses TOML formatting to specify hex values for the theme's visual elements. The shell configuration file determines how these colors apply to specific interface components.

Managing Themes via CLI

The Omarchy CLI provides commands to interact with themes stored in both locations. Use these commands to list, apply, and create themes:

# List all available themes (combines stock + user directories)

omarchy theme list

# Apply a theme by name

omarchy theme set catppuccin

To create a custom theme based on an existing stock theme:

# Create directory structure for custom theme

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

# Copy stock theme files as base

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

# Edit the configuration files, then apply

omarchy theme set my-custom

You can verify the storage locations by listing the directories directly:

# View system-wide stock themes

ls /usr/share/omarchy/themes

# View user-created custom themes

ls ~/.config/omarchy/themes

Summary

• Stock themes are installed at /usr/share/omarchy/themes/<name>/ and ship with the basecamp/omarchy repository
• User themes are stored at ~/.config/omarchy/themes/<name>/ for personal customizations
• Omarchy merges both locations at runtime, presenting a unified list via omarchy theme list
• Required files include colors.toml for palettes and shell.toml or hyprland.lua for UI configuration
• The theme selector (Super + Ctrl + Shift + Space) reads from both directories to apply visual changes

Frequently Asked Questions

Where are Omarchy themes stored on Linux?

Omarchy themes are stored in two distinct Linux paths: stock themes reside in /usr/share/omarchy/themes/<name>/ for system-wide access, while user-specific custom themes are located at ~/.config/omarchy/themes/<name>/ within your home directory. The Omarchy CLI and graphical selector merge both locations at runtime to present all available options.

How do I create a custom Omarchy theme?

Copy an existing stock theme from /usr/share/omarchy/themes/ to ~/.config/omarchy/themes/<your-theme-name>/, then modify the colors.toml and shell.toml files to customize the palette and UI elements. After editing, apply the theme using omarchy theme set <your-theme-name> to see your changes immediately.

What files are required for an Omarchy theme to work?

Every Omarchy theme requires at minimum a colors.toml file that defines the color palette using hex values for accents, backgrounds, and foregrounds. Themes should also include either shell.toml or hyprland.lua to specify UI surface roles and sizing parameters for the desktop environment components.

How do I switch between themes in Omarchy?

Use the CLI command omarchy theme set <theme-name> to switch themes programmatically, or press Super + Ctrl + Shift + Space to open the graphical theme selector. Both methods read from the merged stock and user theme directories, allowing you to switch between system defaults and your custom creations instantly.

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