Where Are Omarchy Themes Stored and What Files Are Involved?

Omarchy themes are stored in system directories under /usr/share/omarchy/themes/, user directories at ~/.config/omarchy/themes/, and staged at runtime in ~/.local/state/omarchy/current/, with activation handled by templates in default/themed/*.tpl and the omarchy-theme-set command.

The Omarchy desktop environment uses a modular theming system defined in the omacom/omarchy repository. Understanding the directory structure and file types is essential for customizing your desktop, terminal colors, and application appearances without breaking system updates.

System and User Theme Storage Locations

Omarchy separates themes into three distinct tiers: system-installed defaults, user-created overrides, and runtime staging areas.

System-Wide Theme Directory

First-party themes ship in the themes/<name>/ path within the source tree. When the Omarchy package is installed, these directories copy to /usr/share/omarchy/themes/<name>/. This location is read-only for regular users and serves as the fallback source during theme activation.

User Custom Themes Directory

Custom themes and user overrides belong in ~/.config/omarchy/themes/<name>/. Files placed here automatically overlay on top of system themes when you run omarchy-theme-set <name>. This separation ensures your customizations survive system updates while allowing you to override specific files without copying entire themes.

Runtime Staging Area

When activating a theme, Omarchy builds a temporary copy in ~/.local/state/omarchy/current/next-theme. The omarchy-theme-set script then moves this staged content into ~/.local/state/omarchy/current/theme/ and symlinks the chosen background. This atomic swap prevents broken mid-transition states while live-reloading the Quickshell process.

Theme Activation Workflow

The bin/omarchy-theme-set script orchestrates a five-step activation flow defined in docs/theming.md:

1. Copy the base theme from themes/<name>/ (or ~/.config/omarchy/themes/<name>/ if user overrides exist).
2. Overlay any user-provided files from the config directory.
3. Generate derived configuration files by rendering templates in default/themed/*.tpl using the palette defined in colors.toml.
4. Stage the compiled result in ~/.local/state/omarchy/current/next-theme.
5. Swap the staged directory into ~/.local/state/omarchy/current/theme and notify the running Quickshell session.

This pipeline ensures that hand-written overrides take precedence over generated content, while templates handle the repetitive task of syncing color values across Hyprland, Alacritty, and shell configurations.

Core Theme Files and Templates

Every Omarchy theme consists of a required palette file and optional assets that customize specific components.

Required Files

• colors.toml – Defines the palette keys (accent, background, foreground, etc.). All templates read from this file to generate application-specific configurations.

Optional Assets

File	Purpose
backgrounds/	Image files for lock screen and desktop wallpapers. User-specific backgrounds may also reside in ~/.config/omarchy/backgrounds/<name>/.
preview.png / preview-unlock.png	Thumbnail images displayed in the theme picker interface.
icons.theme	Specifies the icon set name (e.g., Yaru) to apply.
keyboard.rgb	Defines keyboard backlight color values.
light.mode	Empty marker file indicating a light-mode variant (or use mode = "light" inside colors.toml).
shell.toml, hyprland.lua, etc.	Hand-written overrides that replace generated files for specific components.

Template System

The default/themed/*.tpl files contain built-in templates that transform colors.toml values into concrete configuration files. For example, default/themed/shell.toml.tpl generates the final shell.toml consumed by the desktop environment. When a theme includes its own version of these files (without the .tpl extension), they override the template output entirely.

How to Create and Apply Custom Themes

You can extend Omarchy by copying an existing system theme and modifying its palette.

List installed themes:

omarchy theme list

Activate an existing theme:

omarchy theme set tokyo-night

Create a custom theme from a system template:

cp -r /usr/share/omarchy/themes/tokyo-night ~/.config/omarchy/themes/my-custom
nano ~/.config/omarchy/themes/my-custom/colors.toml
omarchy theme set my-custom

This workflow leverages the overlay system: you only need to store modified files in ~/.config/omarchy/themes/my-custom/, while unchanged files fall back to the system directory.

Summary

• System themes live in /usr/share/omarchy/themes/<name>/ and ship with the package.
• User themes belong in ~/.config/omarchy/themes/<name>/ and overlay system files during activation.
• Runtime staging occurs in ~/.local/state/omarchy/current/ to enable atomic theme swaps.
• colors.toml is the only required file; it drives the template generation system in default/themed/*.tpl.
• bin/omarchy-theme-set handles copy, overlay, template rendering, and live-reloading via Quickshell.

Frequently Asked Questions

Where is the active Omarchy theme stored?

The active theme resides in ~/.local/state/omarchy/current/theme/, which contains the fully processed and merged configuration files ready for consumption by the desktop environment. This directory updates atomically when you switch themes to prevent configuration corruption.

What is the minimum file needed to create a custom theme?

You need only a colors.toml file containing palette definitions such as accent, background, and foreground. Place this in ~/.config/omarchy/themes/<your-name>/colors.toml and run omarchy theme set <your-name>. The template system will generate all other necessary configuration files automatically.

How do I override a system theme without modifying system files?

Place individual override files in ~/.config/omarchy/themes/<theme-name>/ matching the structure of the system theme. For example, to change only the background image for the tokyo-night theme, copy just the backgrounds/ directory or specific image files to ~/.config/omarchy/themes/tokyo-night/backgrounds/. The activation script overlays these onto the base theme during the staging process.

What templates are used to generate configuration files?

Omarchy uses template files located in default/themed/*.tpl within the installation directory. These include templates for shell.toml, hyprland.lua, and alacritty.toml among others. They read values from your theme's colors.toml and output final configuration files to the runtime staging area. You can bypass template generation by providing a hand-written file with the same name (minus the .tpl extension) in your theme directory.

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