Where Omarchy Themes Are Stored and How Theme Activation Works

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 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 and shell.toml

The Theme Activation Pipeline

When you run omarchy theme set <name>, 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/<name> into the staging area. Next, it overlays any user-installed version from $HOME/.config/omarchy/themes/<name>. 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 files.

Template Generation and Background Selection

For themes lacking a colors.toml, the system generates missing colour palettes from an alacritty.toml using the stage_installed_colors_from_alacritty function. The omarchy-theme-set-templates helper then generates dynamic configs such as 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.

# 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/<theme-name>/ 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.

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