# Where Are Omarchy Themes Stored and What Files Are Involved? > Discover where Omarchy themes are stored in system and user directories, detailing involved files like .tpl templates and activation via omarchy-theme-set. Optimize your Omarchy setup now. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-08-30 --- **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](https://github.com/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//` path within the source tree. When the Omarchy package is installed, these directories copy to `/usr/share/omarchy/themes//`. 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//`. Files placed here automatically overlay on top of system themes when you run `omarchy-theme-set `. 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`](https://github.com/omacom/omarchy/blob/main/docs/theming.md): 1. **Copy** the base theme from `themes//` (or `~/.config/omarchy/themes//` 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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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//`. | | `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`](https://github.com/omacom/omarchy/blob/main/colors.toml)). | | [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml), [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/colors.toml) values into concrete configuration files. For example, `default/themed/shell.toml.tpl` generates the final [`shell.toml`](https://github.com/omacom/omarchy/blob/main/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: ```bash omarchy theme list ``` Activate an existing theme: ```bash omarchy theme set tokyo-night ``` Create a custom theme from a system template: ```bash 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//` and ship with the package. - **User themes** belong in `~/.config/omarchy/themes//` and overlay system files during activation. - **Runtime staging** occurs in `~/.local/state/omarchy/current/` to enable atomic theme swaps. - **[`colors.toml`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/colors.toml) file containing palette definitions such as `accent`, `background`, and `foreground`. Place this in `~/.config/omarchy/themes//colors.toml` and run `omarchy theme set `. 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//` 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`](https://github.com/omacom/omarchy/blob/main/shell.toml), [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua), and [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) among others. They read values from your theme's [`colors.toml`](https://github.com/omacom/omarchy/blob/main/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.