# Where Are Omarchy Themes Stored and How They Work: Complete Guide > Discover where Omarchy themes are stored, from stock to custom user themes. Learn how Omarchy merges these directories for easy customization. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-24 --- **Omarchy themes are stored in two locations—stock themes reside in `/usr/share/omarchy/themes/` while custom user themes live in `~/.config/omarchy/themes/`, with both directories merged at runtime to allow seamless customization without modifying system files.** Managing visual customization in the Omarchy desktop environment requires understanding exactly where theme files reside and how the system prioritizes them. Based on the source code from the basecamp/omarchy repository, themes are organized in a hierarchical overlay system that separates system defaults from user modifications. This guide examines the complete file structure, configuration formats, and CLI commands that control Omarchy theming. ## Theme Storage Locations and Directory Structure Omarchy employs a dual-path storage strategy that distinguishes between immutable stock themes and mutable user customizations. According to the theming documentation in [`quattro/docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/quattro/docs/theming.md), the system scans both directories at runtime and presents a unified list to the user. ### Stock Themes in /usr/share/omarchy/themes/ Stock themes ship with the Omarchy repository and are installed system-wide. During installation, the contents of the repository's `themes/` directory are copied to **`/usr/share/omarchy/themes//`**. These directories serve as read-only reference implementations that define the default visual appearance of the desktop environment. Each stock theme directory contains at minimum a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file defining the color palette, and may include additional configuration files like [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua) that specify UI surface roles and window sizing parameters. ### User-Installed Custom Themes in ~/.config/omarchy/themes/ User themes reside in **`~/.config/omarchy/themes//`** and follow the same internal structure as stock themes. This location allows users to create custom color schemes without requiring root privileges or modifying system files. The overlay system ensures that when a user selects a custom theme name matching a stock theme, the user version takes precedence. As documented in [`manual/43-making-your-own-theme.md`](https://github.com/basecamp/omarchy/blob/main/manual/43-making-your-own-theme.md), creating a custom theme typically involves copying a stock theme from `/usr/share/omarchy/themes/` into the user directory, then editing the constituent files to modify colors and layout properties. ## Theme File Structure and Configuration Files Individual themes are not single files but directories containing specific TOML and Lua configuration files. The Omarchy theme engine parses these files to construct the complete visual environment, affecting everything from the top bar to terminal applications. ### colors.toml Palette Definition The **[`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml)** file serves as the primary palette definition, specifying accent colors, background values, foreground text colors, and semantic color roles. This file is mandatory for every theme and uses a straightforward key-value structure that the system reads during theme initialization. ### shell.toml and hyprland.lua UI Configuration Beyond color definitions, themes may include **[`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml)** or alternatively **[`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua)** to define UI surface roles, window sizing, spacing parameters, and layout-specific overrides. These files control the structural presentation of Omarchy interface elements, including the top bar dimensions, splash screen positioning, and terminal-side application layouts. ## How to List, Apply, and Create Omarchy Themes The Omarchy CLI provides unified access to both stock and user themes, automatically merging the two storage locations into a single selectable inventory. List available themes from both locations: ```bash omarchy theme list ``` Apply a theme by name: ```bash omarchy theme set catppuccin ``` Create a custom theme by copying a stock reference and editing the configuration: ```bash mkdir -p ~/.config/omarchy/themes/my-custom cp /usr/share/omarchy/themes/catppuccin/colors.toml ~/.config/omarchy/themes/my-custom/ # Edit ~/.config/omarchy/themes/my-custom/colors.toml as desired omarchy theme set my-custom ``` Verify the storage locations directly: ```bash ls /usr/share/omarchy/themes # Stock themes ls ~/.config/omarchy/themes # User themes ``` The theme selector interface, accessible via **Super + Ctrl + Shift + Space**, draws from these configuration files to restyle the entire UI hierarchy dynamically. ## Summary - Omarchy themes exist in two distinct tiers: system stock themes under `/usr/share/omarchy/themes/` and user customizations in `~/.config/omarchy/themes/`. - Every theme directory requires at minimum a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file to define the color palette. - Advanced theming utilizes [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua) for UI surface roles and sizing adjustments. - The `omarchy` CLI command automatically merges both storage locations, allowing seamless switching between stock and custom themes without file path concerns. - User themes override stock themes of the same name, enabling safe customization workflows that preserve system defaults. ## Frequently Asked Questions ### Where are Omarchy themes stored by default? Stock themes are installed to `/usr/share/omarchy/themes//` during system installation, while user-created or modified themes reside in `~/.config/omarchy/themes//`. The Omarchy CLI reads both locations simultaneously and presents them as a unified list when running `omarchy theme list`. ### What files are required to create a custom Omarchy theme? A valid Omarchy theme requires at minimum a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file containing palette definitions for accent, background, and foreground colors. Optional files include [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua) for defining UI surface roles, window sizing, and layout-specific configurations that control the appearance of the top bar and splash screen. ### How do I switch between themes in Omarchy? Use the command-line interface with `omarchy theme set ` to apply any available theme immediately. Alternatively, press **Super + Ctrl + Shift + Space** to open the graphical theme selector, which parses the [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) and [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) files from both stock and user directories to restyle the desktop environment. ### Can I override stock themes without modifying system files? Yes. Copy any stock theme from `/usr/share/omarchy/themes//` to `~/.config/omarchy/themes//` and modify the files there. The user directory takes precedence in the overlay system, meaning your custom version will override the stock theme when selected, leaving the original system files untouched.