# Where Are Omarchy Themes Stored and How Are They Structured? > Discover where Omarchy themes are stored and how they are structured. Learn about stock and custom theme locations, colors.toml, and UI configuration files like shell.toml and hyprland.lua. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-25 --- **Omarchy themes are stored in two locations—stock themes in `/usr/share/omarchy/themes/` and custom user themes in `~/.config/omarchy/themes/`—with each theme containing a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) palette definition and optional [`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 configuration.** Omarchy, the opinionated Linux desktop environment from Basecamp, uses a dual-path theme system that merges stock and user configurations at runtime. Understanding where Omarchy themes are stored and how the file structure works is essential for customizing your desktop's appearance. This guide breaks down the exact file paths, configuration formats, and CLI commands used to manage themes in the basecamp/omarchy repository. ## Stock Theme Storage Location Stock themes ship with the Omarchy repository in the `themes/` directory and are installed system-wide at **`/usr/share/omarchy/themes//`**. These directories contain the base color palettes and UI definitions that apply to the top bar, splash screen, and terminal-side applications. According to the theming documentation in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md), the repository layout places theme files under `themes//` before installation. When Omarchy is installed, these files copy to the system share directory, making them available to all users. The Omarchy CLI reads this location when executing `omarchy theme list`, presenting stock themes alongside any user customizations. System-wide themes require root privileges to modify, which is why Omarchy implements a user overlay system for safe customization. ## User Theme Storage and Overrides Custom themes reside in **`~/.config/omarchy/themes//`** within your home directory. As documented in [`manual/43-making-your-own-theme.md`](https://github.com/basecamp/omarchy/blob/main/manual/43-making-your-own-theme.md), this location allows users to copy existing stock themes as a base template, edit the configuration files, and apply the overlay automatically when the theme is selected. The runtime merging works hierarchically: Omarchy checks the user configuration directory first, then falls back to the system stock directory. This means files in `~/.config/omarchy/themes/my-custom/` override their counterparts in `/usr/share/omarchy/themes/my-custom/`, while unspecified values inherit from stock defaults. To create a custom theme, copy a stock theme's structure to your user directory: ```bash mkdir -p ~/.config/omarchy/themes/my-custom cp /usr/share/omarchy/themes/catppuccin/colors.toml \ ~/.config/omarchy/themes/my-custom/ ``` After editing the files, apply your custom theme without affecting system-wide installations: ```bash omarchy theme set my-custom ``` ## Theme File Structure and Configuration Files Each Omarchy theme directory contains specific configuration files that define visual appearance and layout behavior. According to the source structure in `themes/catppuccin/`, the two primary files are: **[`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml)** – Defines the color palette including accent colors, background, foreground, and terminal color mappings. This file is mandatory for every theme. **[`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua)** – Configures UI surface roles, sizing, and layout-specific overrides for the Hyprland compositor. These files are optional but required for advanced UI customization. When you activate a theme via the CLI or the theme selector (accessed via **`Super + Ctrl + Shift + Space`**), Omarchy reads [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) to set the palette and checks for [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua) to adjust surface roles and dimensions. ## How to List and Apply Themes Using the CLI The Omarchy CLI provides straightforward commands for theme management that aggregate both storage locations. The `omarchy theme list` command scans `/usr/share/omarchy/themes/` and `~/.config/omarchy/themes/`, presenting a unified list of available options. List all available themes including both stock and custom installations: ```bash omarchy theme list ``` Apply a specific theme by its directory name: ```bash omarchy theme set catppuccin ``` Verify the installation locations and explore available stock themes: ```bash ls /usr/share/omarchy/themes ls ~/.config/omarchy/themes ``` The CLI automatically resolves which storage location contains the requested theme, applying user overlays when present or falling back to system defaults. ## Summary - **Stock themes** are installed at `/usr/share/omarchy/themes//` and ship with the basecamp/omarchy repository. - **User themes** belong in `~/.config/omarchy/themes//` and override stock configurations at runtime. - **Required files**: Each theme must contain [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) defining the color palette. - **Optional files**: [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua) configure UI surface roles and sizing for the Hyprland compositor. - **CLI commands**: Use `omarchy theme list` to view merged theme lists and `omarchy theme set ` to apply themes from either location. ## Frequently Asked Questions ### What file format does Omarchy use for theme colors? Omarchy uses **TOML format** for color definitions in the [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file. This file resides in each theme directory and specifies hex values for accent colors, background, foreground, and terminal-specific color mappings. ### Can I modify stock themes directly in `/usr/share/omarchy/themes/`? You should not modify stock themes directly, as these files are managed by the system package manager. Instead, copy the stock theme directory to `~/.config/omarchy/themes//` using the `cp` command, then edit the files in your user directory. Omarchy will prioritize your user configuration while maintaining system integrity. ### How do I switch between themes without using the terminal? You can access the **theme selector** using the keyboard shortcut **`Super + Ctrl + Shift + Space`**. This graphical interface reads both storage locations, extracts color data from [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml), and applies the selected theme immediately across the top bar, splash screen, and terminal applications. ### Where does Omarchy look first when loading a theme? Omarchy follows an overlay hierarchy, checking **`~/.config/omarchy/themes//`** before falling back to **`/usr/share/omarchy/themes//`**. If a file exists in both locations, the user configuration takes precedence, allowing partial overrides without duplicating entire theme definitions.