Where Are Omarchy Themes Stored and How Are They Structured?

Omarchy themes are stored in two locations—stock themes in /usr/share/omarchy/themes/ and custom user themes in ~/.config/omarchy/themes/—with each theme containing a colors.toml palette definition and optional shell.toml or hyprland.lua for UI surface configuration.

Omarchy, the opinionated Linux desktop environment from Basecamp, uses a dual-path theme system that merges stock and user configurations at runtime. Understanding where Omarchy themes are stored and how the file structure works is essential for customizing your desktop's appearance. This guide breaks down the exact file paths, configuration formats, and CLI commands used to manage themes in the basecamp/omarchy repository.

Stock Theme Storage Location

Stock themes ship with the Omarchy repository in the themes/ directory and are installed system-wide at /usr/share/omarchy/themes/<name>/. These directories contain the base color palettes and UI definitions that apply to the top bar, splash screen, and terminal-side applications.

According to the theming documentation in docs/theming.md, the repository layout places theme files under themes/<name>/ before installation. When Omarchy is installed, these files copy to the system share directory, making them available to all users. The Omarchy CLI reads this location when executing omarchy theme list, presenting stock themes alongside any user customizations.

System-wide themes require root privileges to modify, which is why Omarchy implements a user overlay system for safe customization.

User Theme Storage and Overrides

Custom themes reside in ~/.config/omarchy/themes/<name>/ within your home directory. As documented in manual/43-making-your-own-theme.md, this location allows users to copy existing stock themes as a base template, edit the configuration files, and apply the overlay automatically when the theme is selected.

The runtime merging works hierarchically: Omarchy checks the user configuration directory first, then falls back to the system stock directory. This means files in ~/.config/omarchy/themes/my-custom/ override their counterparts in /usr/share/omarchy/themes/my-custom/, while unspecified values inherit from stock defaults.

To create a custom theme, copy a stock theme's structure to your user directory:

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

After editing the files, apply your custom theme without affecting system-wide installations:

omarchy theme set my-custom

Theme File Structure and Configuration Files

Each Omarchy theme directory contains specific configuration files that define visual appearance and layout behavior. According to the source structure in themes/catppuccin/, the two primary files are:

colors.toml – Defines the color palette including accent colors, background, foreground, and terminal color mappings. This file is mandatory for every theme.

shell.toml or hyprland.lua – Configures UI surface roles, sizing, and layout-specific overrides for the Hyprland compositor. These files are optional but required for advanced UI customization.

When you activate a theme via the CLI or the theme selector (accessed via Super + Ctrl + Shift + Space), Omarchy reads colors.toml to set the palette and checks for shell.toml or hyprland.lua to adjust surface roles and dimensions.

How to List and Apply Themes Using the CLI

The Omarchy CLI provides straightforward commands for theme management that aggregate both storage locations. The omarchy theme list command scans /usr/share/omarchy/themes/ and ~/.config/omarchy/themes/, presenting a unified list of available options.

List all available themes including both stock and custom installations:

omarchy theme list

Apply a specific theme by its directory name:

omarchy theme set catppuccin

Verify the installation locations and explore available stock themes:

ls /usr/share/omarchy/themes
ls ~/.config/omarchy/themes

The CLI automatically resolves which storage location contains the requested theme, applying user overlays when present or falling back to system defaults.

Summary

• Stock themes are installed at /usr/share/omarchy/themes/<name>/ and ship with the basecamp/omarchy repository.
• User themes belong in ~/.config/omarchy/themes/<name>/ and override stock configurations at runtime.
• Required files: Each theme must contain colors.toml defining the color palette.
• Optional files: shell.toml or hyprland.lua configure UI surface roles and sizing for the Hyprland compositor.
• CLI commands: Use omarchy theme list to view merged theme lists and omarchy theme set <name> to apply themes from either location.

Frequently Asked Questions

What file format does Omarchy use for theme colors?

Omarchy uses TOML format for color definitions in the colors.toml file. This file resides in each theme directory and specifies hex values for accent colors, background, foreground, and terminal-specific color mappings.

Can I modify stock themes directly in /usr/share/omarchy/themes/?

You should not modify stock themes directly, as these files are managed by the system package manager. Instead, copy the stock theme directory to ~/.config/omarchy/themes/<name>/ using the cp command, then edit the files in your user directory. Omarchy will prioritize your user configuration while maintaining system integrity.

How do I switch between themes without using the terminal?

You can access the theme selector using the keyboard shortcut Super + Ctrl + Shift + Space. This graphical interface reads both storage locations, extracts color data from colors.toml, and applies the selected theme immediately across the top bar, splash screen, and terminal applications.

Where does Omarchy look first when loading a theme?

Omarchy follows an overlay hierarchy, checking ~/.config/omarchy/themes/<name>/ before falling back to /usr/share/omarchy/themes/<name>/. If a file exists in both locations, the user configuration takes precedence, allowing partial overrides without duplicating entire theme definitions.

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