# How to Apply a Theme in Omarchy: CLI, UI, and Custom Configuration Methods > Learn how to apply a theme in Omarchy using the CLI, hotkey, or status bar. Customize your Omarchy experience with these easy methods. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-26 --- **You can apply a theme in Omarchy using the `omarchy theme set ` CLI command, the Super + Ctrl + Shift + Space hotkey to open the theme selector, or the clickable theme-switcher panel in the status bar.** Omarchy is a Linux desktop environment developed by Basecamp that uses a centralized theme singleton to control the color palette across all visual components. Learning how to apply a theme in Omarchy allows you to instantly change the appearance of your bar, terminal, editors, and lock screen through multiple interface options. The theming system stores the active theme name in `~/.local/state/omarchy/current/` and propagates changes automatically to all templated configuration files. ## Understanding Omarchy's Theme Architecture Omarchy's theming engine relies on a **theme singleton** that maintains a complete color palette consumed by every visual component. When you apply a theme, this singleton updates its state and triggers a cascade of configuration refreshes affecting the bar, menu, notifications, lock screen, terminal, and background picker. ### Theme Storage Locations Themes reside in three primary locations according to the [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) specification: - **System themes**: `/usr/share/omarchy/themes//` - **Repository themes**: `themes//` (in the basecamp/omarchy source) - **User custom themes**: `~/.config/omarchy/themes//` The theme selector automatically detects themes installed in any of these directories, with user-defined themes in `~/.config/omarchy/themes/` taking precedence for custom modifications. ## Methods to Apply a Theme in Omarchy You can change the active theme through three primary interfaces, all of which update the same centralized state in `~/.local/state/omarchy/current/`. ### Using the CLI Command The most direct method to apply a theme in Omarchy is the `omarchy theme set` command. As documented in [`manual/14-omarchy-cli.md`](https://github.com/basecamp/omarchy/blob/main/manual/14-omarchy-cli.md), this command updates the theme singleton's current state, regenerates all templated configuration files, and refreshes the desktop environment immediately. ```bash # List all available themes omarchy theme list # Apply the "tokyo-night" theme omarchy theme set tokyo-night ``` The [`install/user/theme.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/theme.sh) script handles the backend logic, ensuring that configurations for Alacritty, Foot, Helix, and other templated applications receive the new color values. ### Using the UI and Hotkeys For graphical selection, open the **Omarchy menu** and navigate to `Install → Style → Theme`. Alternatively, use the dedicated hotkey documented in [`manual/07-hotkeys.md`](https://github.com/basecamp/omarchy/blob/main/manual/07-hotkeys.md). Press **Super + Ctrl + Shift + Space** to open the theme selector UI directly without navigating menus. Selecting a theme through the UI triggers the same backend `omarchy theme set` logic used by the CLI, ensuring consistent behavior across interfaces. ### Using the Theme Switcher Panel The `omarchy-theme-switcher` panel, described in [`shell/plugins/bar/README.md`](https://github.com/basecamp/omarchy/blob/main/shell/plugins/bar/README.md), provides a clickable list of available themes integrated into the status bar. Clicking any theme name invokes the internal configuration routine, executing an instant visual refresh without requiring terminal access. ## How Theme Changes Propagate When you apply a theme in Omarchy, the system executes a **refresh pipeline** that ensures every component reflects the new palette simultaneously. ### The Refresh Pipeline The `omarchy theme set` command initiates the `omarchy refresh-config` infrastructure, which copies templated configuration files from `default/themed/` into your `~/.config/` directory. This process interpolates palette values into application-specific formats: - [`alacritty.toml`](https://github.com/basecamp/omarchy/blob/main/alacritty.toml) for the Alacritty terminal - [`foot.ini`](https://github.com/basecamp/omarchy/blob/main/foot.ini) for the Foot terminal - [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) for shell theming As implemented in [`install/user/theme.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/theme.sh), this guarantees that all supported applications receive consistent color updates immediately upon theme application. ### Background Image Handling Themes may ship with dedicated background images stored in `themes//backgrounds/`. You can add custom images to `~/.config/omarchy/backgrounds//` according to [`manual/39-backgrounds.md`](https://github.com/basecamp/omarchy/blob/main/manual/39-backgrounds.md). The background picker, accessible via **Super + Ctrl + Space**, displays only images belonging to the currently active theme. To refresh background availability after adding images, reapply the current theme: ```bash # Add a custom background to the current theme's directory mkdir -p ~/.config/omarchy/backgrounds/$(omarchy theme get) cp ~/Downloads/wallpaper.png ~/.config/omarchy/backgrounds/$(omarchy theme get)/ # Refresh the background picker by reapplying the current theme omarchy theme set $(omarchy theme get) ``` ## Installing Custom Themes To install a custom theme in Omarchy, create a directory matching the theme name in `~/.config/omarchy/themes//` containing the required theme configuration files. The theme selector automatically detects new additions without requiring a system restart, allowing immediate application via any of the methods described above. ## Summary - **Apply themes via CLI** using `omarchy theme set ` for programmatic control and scripting - **Use UI shortcuts** like Super + Ctrl + Shift + Space for quick visual browsing - **Access the theme-switcher panel** in the status bar for mouse-driven theme changes - **Store custom themes** in `~/.config/omarchy/themes//` for automatic detection - **Leverage the refresh pipeline** to ensure Alacritty, Foot, Helix, and other apps update instantly - **Manage backgrounds** per-theme in `~/.config/omarchy/backgrounds//` ## Frequently Asked Questions ### Where are themes stored in Omarchy? System-wide themes reside in `/usr/share/omarchy/themes//`, while user-specific themes belong in `~/.config/omarchy/themes//`. The theme selector scans both locations and lists all available themes automatically, as defined in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md). ### How do I apply a theme using the keyboard shortcut? Press **Super + Ctrl + Shift + Space** to open the theme selector UI instantly. This hotkey, defined in [`manual/07-hotkeys.md`](https://github.com/basecamp/omarchy/blob/main/manual/07-hotkeys.md), bypasses the menu navigation and presents a searchable list of all installed themes. ### Can I use custom background images with any theme? Yes. Create a directory at `~/.config/omarchy/backgrounds//` and place your images there. The background picker (Super + Ctrl + Space) filters images to show only those matching the currently active theme, as documented in [`manual/39-backgrounds.md`](https://github.com/basecamp/omarchy/blob/main/manual/39-backgrounds.md). ### What files does Omarchy update when switching themes? The `omarchy theme set` command triggers [`install/user/theme.sh`](https://github.com/basecamp/omarchy/blob/main/install/user/theme.sh) to regenerate templated configurations including [`alacritty.toml`](https://github.com/basecamp/omarchy/blob/main/alacritty.toml), [`foot.ini`](https://github.com/basecamp/omarchy/blob/main/foot.ini), and [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) in your `~/.config/` directory. It also updates the symlink for the current background and refreshes all shell components that consume the theme singleton.