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

> Learn how to set a new Omarchy theme with our complete guide. Activate custom themes easily using omarchy-theme-set and understand the staged rendering pipeline for seamless theme deployment.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-theme-set) orchestrates the entire process.

### Basic Usage

```bash

# 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`:

```bash

# 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/main/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/main/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:

```bash

# 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/main/install/user/theme.sh)](https://github.com/omacom/omarchy/blob/quattro/install/user/theme.sh):

```bash

# 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:

```bash
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:

```bash
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`](https://github.com/omacom/omarchy/blob/main/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/main/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`](https://github.com/omacom/omarchy/blob/quattro/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/main/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.