# Where Omarchy Themes Are Stored and How Theme Activation Works > Discover where Omarchy themes are stored in $OMARCHY_PATH/themes/ and ~/.config/omarchy/themes/. Learn how the omarchy-theme-set script activates themes and updates your Quickshell session. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-08 --- **Omarchy stores themes in distinct filesystem locations—bundled themes at `$OMARCHY_PATH/themes/` and user themes at `~/.config/omarchy/themes/`—and activates them via the `omarchy-theme-set` script, which stages, merges, and symlinks the selected theme into `~/.local/state/omarchy/current/` before broadcasting palette changes to the running Quickshell session.** Omarchy manages desktop theming through a hierarchical filesystem architecture that separates read-only system themes from user customizations. Understanding where Omarchy themes are stored and how the activation pipeline works is essential for customizing your Hyprland-based desktop environment. The system uses atomic staging, file overlay logic, and IPC broadcasting to switch themes without breaking the active session. ## Filesystem Storage Architecture Omarchy’s theme system relies on three specific directories that handle different stages of theme persistence and activation. ### Bundled Themes **Bundled themes** reside in `{{OMARCHY_PATH}}/themes/` (repository path `themes/`). This directory contains read-only theme packs shipped with the Omarchy distribution. Each theme folder holds a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) configuration, optional background images or video files, an `icons.theme` file, Lua snippets for Hyprland integration, and optional editor or terminal templates. ### User-Installed Themes **User-installed themes** live in `~/.config/omarchy/themes/`. This writable directory allows users to drop custom themes or clone themes from Git repositories. Themes placed here overlay the bundled versions, enabling partial customization without modifying system files. ### Current Theme State The **active theme state** is maintained in `~/.local/state/omarchy/current/`. This directory contains: - Two symlinks: `theme` (pointing to the active theme directory) and `background` (pointing to the active background file) - Metadata files: `theme.name` and staged configuration files including [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) and [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml) ## The Theme Activation Pipeline When you run `omarchy theme set `, the **`omarchy-theme-set`** script (source: `bin/omarchy-theme-set`) executes an eleven-step pipeline to safely transition the desktop environment. ### Validation and Staging The script first validates the theme name and resolves it to a safe directory name. It then acquires a file lock using `flock` to prevent race conditions during concurrent theme switches. The system prepares a clean staging area at `$HOME/.local/state/omarchy/current/next-theme` for atomic operations. ### Theme Merging and Overlay Logic The activation process copies the bundled theme from `$OMARCHY_PATH/themes/` into the staging area. Next, it overlays any user-installed version from `$HOME/.config/omarchy/themes/`. If the user theme originated from a Git repository, the script filters files according to the `INSTALLED_THEME_DENIED` array—copying allowed files like colors and images while rejecting Lua scripts, terminal configs, and [`vscode.json`](https://github.com/omacom/omarchy/blob/main/vscode.json) files. ### Template Generation and Background Selection For themes lacking a [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), the system generates missing colour palettes from an [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) using the `stage_installed_colors_from_alacritty` function. The `omarchy-theme-set-templates` helper then generates dynamic configs such as [`shell.toml`](https://github.com/omacom/omarchy/blob/main/shell.toml). Background selection occurs via `choose_theme_background` and `choose_staged_theme_background`, handling snapshot-based transitions for smooth visual changes. ### Atomic Swap and IPC Broadcasting The script swaps the staged theme into `CURRENT_THEME_PATH` (`~/.local/state/omarchy/current/theme`) and updates the symlinks. It then broadcasts the new palette to the running Quickshell session via `shell_ipc`. Finally, it executes post-theme hooks in parallel—restarting terminals, Hyprland, btop, and VS Code—before preloading the theme picker UI using `omarchy-theme-switcher --preload`. ## Practical Theme Management Commands The **`omarchy-theme-dir`** helper (source: `bin/omarchy-theme-dir`) resolves which directory will be used for a given theme, preferring the user-installed copy over the bundled version. ```bash # List available themes omarchy theme list # Show the resolved path for a theme (prefers user copy) omarchy theme dir "Tokyo Night" # → /home/alice/.config/omarchy/themes/tokyo-night (if it exists) # Activate a theme called "Tokyo Night" omarchy theme set "Tokyo Night" # Verify the active theme directory readlink -f ~/.local/state/omarchy/current/theme # → /home/alice/.local/state/omarchy/current/theme ``` ## Summary - Omarchy maintains themes in two primary locations: bundled themes at `$OMARCHY_PATH/themes/` and user overrides at `~/.config/omarchy/themes/`. - The active theme state lives in `~/.local/state/omarchy/current/` with symlinks managing the current selection. - The `omarchy-theme-set` script handles activation through atomic staging, file overlay with security filtering, template generation, and IPC broadcasting. - User themes overlay bundled themes but respect the `INSTALLED_THEME_DENIED` filter for security. - Background transitions and application restarts occur automatically after the theme swap completes. ## Frequently Asked Questions ### Where does Omarchy store the currently active theme? Omarchy stores the currently active theme in `~/.local/state/omarchy/current/`, which contains symlinks named `theme` and `background` pointing to the active theme directory and background file respectively, along with metadata files like `theme.name` and staged configuration files. ### Can I override bundled themes with custom configurations? Yes. Place your custom theme in `~/.config/omarchy/themes//` and Omarchy will overlay your files over the bundled version during activation. The `omarchy-theme-dir` helper prioritizes the user directory when resolving theme paths. ### How does Omarchy prevent malicious files in user-installed themes? When activating a theme from a Git repository, the `omarchy-theme-set` script filters files using the `INSTALLED_THEME_DENIED` array, which blocks executable code like Lua scripts, terminal configurations, and JSON files while allowing safe assets like colors, images, and icons. ### What happens to running applications when I switch themes? The `omarchy-theme-set` script broadcasts the new palette via `shell_ipc` to the running Quickshell session, then executes post-theme hooks in parallel to restart terminals, Hyprland, btop, and VS Code, ensuring all applications reflect the new theme simultaneously.