How to Apply a Theme in Omarchy: CLI, UI, and Custom Configuration Methods

You can apply a theme in Omarchy using the omarchy theme set <name> 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 specification:

• System themes: /usr/share/omarchy/themes/<name>/
• Repository themes: themes/<name>/ (in the basecamp/omarchy source)
• User custom themes: ~/.config/omarchy/themes/<name>/

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, this command updates the theme singleton's current state, regenerates all templated configuration files, and refreshes the desktop environment immediately.

# List all available themes

omarchy theme list

# Apply the "tokyo-night" theme

omarchy theme set tokyo-night

The 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.

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, 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 for the Alacritty terminal
• foot.ini for the Foot terminal
• shell.toml for shell theming

As implemented in 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/<name>/backgrounds/. You can add custom images to ~/.config/omarchy/backgrounds/<theme>/ according to 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:

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

Frequently Asked Questions

Where are themes stored in Omarchy?

System-wide themes reside in /usr/share/omarchy/themes/<name>/, while user-specific themes belong in ~/.config/omarchy/themes/<name>/. The theme selector scans both locations and lists all available themes automatically, as defined in 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, 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/<theme-name>/ 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.

What files does Omarchy update when switching themes?

The omarchy theme set command triggers install/user/theme.sh to regenerate templated configurations including alacritty.toml, foot.ini, and 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.

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