How to Set a New Omarchy Theme: Complete Guide to Theme Activation

Omarchy uses a staged rendering pipeline where omarchy-theme-set <theme-name> prepares theme assets in a clean staging directory, renders templates against theme data, and activates the result via the theme-set hook.

This guide walks through the exact process for setting a new theme in Omarchy, including built-in themes, custom themes, and headless deployment scenarios.

Understanding the Omarchy Theme System

Omarchy themes live under the top-level themes/ directory. Each theme folder contains:

• Colour definitions (colors.toml)
• Optional templates (*.tpl)
• Assets (icons, btop configurations, Alacritty fragments)

The system separates staging (preparation) from activation (deployment), ensuring atomic theme switches and safe rollback.

Setting a Theme: The Core Command

The omarchy-theme-set binary in bin/omarchy-theme-set orchestrates the entire process.

Basic Usage

# Apply a built-in theme

omarchy-theme-set "Tokyo Night"

# Apply a custom theme from themes/

omarchy-theme-set "My Custom Theme"

What Happens When You Run This

1. Staging directory creation — A clean temporary space is prepared for theme assembly
2. File copying — Theme assets are copied into the staging area
3. Template rendering — Files matching default/themed/*.tpl are processed against theme data
4. Hook execution — The theme-set hook fires, updating subsystems (btop, Alacritty, starship, etc.)
5. Activation — Rendered files are copied to user configuration locations (~/.config/...)

Headless Mode for Automated Deployment

For non-interactive environments—first-boot scripts, CI pipelines, or remote provisioning—set OMARCHY_THEME_HEADLESS=1:

# Silent theme application without prompts

OMARCHY_THEME_HEADLESS=1 omarchy-theme-set "Tokyo Night"

This mode is used by the installer in [install/user/theme.sh](https://github.com/omacom/omarchy/blob/quattro/install/user/theme.sh) to apply the default theme during initial setup.

Creating and Testing Custom Themes

Directory Structure

Place your custom theme under themes/<your-theme-name>/:

themes/
└── My Custom Theme/
    ├── colors.toml
    ├── icons/
    ├── btop/
    └── alacritty/

Validation Before Activation

The test suite in [test/shell.d/theme-staging-test.sh](https://github.com/omacom/omarchy/blob/quattro/test/shell.d/theme-staging-test.sh) verifies:

• Disallowed files are ignored during staging
• Symlinks are rejected (security hardening)
• Stock themes overlay correctly on base templates

Run these tests to validate your theme follows Omarchy's constraints:

# Execute theme staging tests

./test/shell.d/theme-staging-test.sh

First-Run Theme Installation

The installer applies the default theme automatically via [install/user/theme.sh](https://github.com/omacom/omarchy/blob/quattro/install/user/theme.sh):

# Excerpt from install/user/theme.sh

omarchy-theme-set "Tokyo Night"

You can override this by specifying a different theme in your preseed configuration or by running omarchy-theme-set manually post-installation.

Listing Available Themes

Before setting a theme, discover what's installed:

omarchy-theme-list

This enumerates both built-in themes from the repository and any custom themes you've added to themes/.

Pi-Specific Theme Activation

For Raspberry Pi deployments, use the dedicated setter:

HOME="$HOME/.config" omarchy-theme-set-pi --activate

This variant applies Pi-specific UI adjustments alongside the standard theme pipeline.

Summary

• Primary command: omarchy-theme-set "<theme-name>" applies any theme from themes/
• Headless automation: OMARCHY_THEME_HEADLESS=1 enables scriptable, non-interactive deployment
• Staging safety: The two-phase staging→activation process prevents broken configurations
• Template system: default/themed/*.tpl files render dynamically per theme
• Validation: test/shell.d/theme-staging-test.sh enforces theme integrity constraints

Frequently Asked Questions

How do I make a custom theme the default for new installations?

Edit [install/user/theme.sh](https://github.com/omacom/omarchy/blob/quattro/install/user/theme.sh) or set the theme via environment variable before running the installer. The script calls omarchy-theme-set with your preferred theme name during the user setup phase.

Can I preview a theme without applying it?

Omarchy's staging mechanism creates a temporary directory with rendered templates. While there's no dedicated --dry-run flag, you can inspect the staging logic in bin/omarchy-theme-set and examine the temporary directory before the activation hook runs.

Why does Omarchy use a staging directory instead of direct file modification?

The staging approach ensures atomic theme switches: if template rendering fails or validation errors occur, your active configuration remains untouched. Only after successful staging does the theme-set hook copy files to ~/.config/ locations.

What file types are allowed in theme directories?

According to the test suite in [test/shell.d/theme-staging-test.sh](https://github.com/omacom/omarchy/blob/quattro/test/shell.d/theme-staging-test.sh), themes may include regular files and directories. Symbolic links are explicitly rejected for security, and certain disallowed file patterns are filtered during the staging process.

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