# How to Migrate an Omarchy Theme from alacritty.toml to colors.toml

> Learn how to migrate your Omarchy theme from alacritty.toml to colors.toml. This guide simplifies theme management and ensures compatibility with the latest Omarchy structure.

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

---

**Migrating an Omarchy theme from [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) to [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) requires extracting the color palette from the legacy terminal configuration, creating a standardized [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) file in the theme directory, and removing the old [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) to let Omarchy generate a fresh terminal config from its template.**

Omarchy themes have shifted from shipping terminal-specific configurations to using a centralized palette system. When **migrating an Omarchy theme from [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) to [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml)**, you convert legacy color definitions into the modern schema used by the `omacom/omarchy` repository to generate consistent theming across all applications. This process ensures your theme follows the current architecture where [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) serves as the single source of truth.

## How Omarchy Handles Legacy Themes Automatically

When a theme lacks [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), Omarchy detects this during **theme staging** in `bin/omarchy-theme-set` (lines 313-314). The system automatically invokes the helper **`omarchy-theme-colors-from-alacritty`** to parse the palette from [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) and write a temporary [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) into a scratch directory.

However, the original [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) is **never copied** into the active theme (lines 186-202 of `bin/omarchy-theme-set`). This means the legacy configuration is discarded during staging, and only the extracted palette survives. While this automatic conversion ensures themes remain functional, theme authors should perform a manual migration to clean up source repositories and ensure long-term maintainability.

## Step-by-Step Migration Process

### Step 1: Extract the Palette from alacritty.toml

Identify all color definitions in your existing [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml). The conversion routine reads standard palette keys including `foreground`, `background`, `accent`, `selection`, `muted`, `red`, `green`, `yellow`, `blue`, `magenta`, and `cyan`.

Copy these hex values into a temporary reference. For example, note values like `foreground = "#a9b1d6"` and `accent = "#7aa2f7"` for transplantation into the new structure.

### Step 2: Create the New colors.toml File

Create [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) in your theme directory (`themes/<name>/colors.toml`) using the standardized schema documented in [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md) (lines 70-93). The file must declare the mode and define all palette variables.

```toml
mode = "dark"

accent = "#7aa2f7"
selection = "#292e42"
muted = "#414868"

background = "#1a1b26"
dark_background = "#13141c"
darker_background = "#0e0e14"
lighter_background = "#24283b"

foreground = "#a9b1d6"
dark_foreground = "#565f89"
light_foreground = "#b4bee6"
bright_foreground = "#c0caf5"

red = "#f7768e"
green = "#9ece6a"
yellow = "#e0af68"
blue = "#7aa2f7"
magenta = "#bb9af7"
cyan = "#7dcfff"

```

This hierarchical structure replaces the flat Alacritty configuration and enables Omarchy to generate configurations for multiple applications from a single source.

### Step 3: Remove the Legacy alacritty.toml

Delete the old [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) from your theme directory. Omarchy will automatically generate a fresh terminal configuration using the template `default/themed/alacritty.toml.tpl` rendered with values from your new [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml).

The generated file is written to `~/.local/state/omarchy/current/theme/alacritty.toml` when you apply the theme. Keeping the legacy file in the theme directory prevents Omarchy from using the standardized generation pipeline and may cause configuration drift.

### Step 4: Verify the Migration with Testing

Activate your migrated theme and run the test suites to ensure no legacy configuration leaks into the staged environment:

```bash
omarchy theme set my-theme
./test/cli
./test/shell

```

The shell tests in [`test/shell.d/theme-staging-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/theme-staging-test.sh) (lines 134-160) include assertions like `assert_no_marker alacritty.toml` to verify that legacy terminal configs are correctly excluded from the active theme at `~/.local/state/omarchy/current/theme/`.

## Understanding the Theme Generation Flow

When you apply a theme containing [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml), Omarchy renders `default/themed/alacritty.toml.tpl` with values from your palette. This ensures the terminal configuration stays synchronized with the central color definitions.

If you need a custom terminal configuration that differs from the generated defaults, you may keep a manually edited [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) in the theme directory. However, this breaks the single-source-of-truth model and is not recommended for standard themes, as it prevents automatic updates when the core template improves.

## Summary

- **Modern Omarchy themes** use [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) as the central palette definition, replacing legacy [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) files that were parsed at install-time.
- **Automatic conversion** occurs during staging via `bin/omarchy-theme-colors-from-alacritty` when [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) is missing, but manual migration is required for clean theme maintenance.
- **Key files** involved include `bin/omarchy-theme-set` for staging logic, [`docs/theming.md`](https://github.com/omacom/omarchy/blob/main/docs/theming.md) for the schema reference, and `default/themed/alacritty.toml.tpl` for terminal generation.
- **Testing** with `./test/cli` and `./test/shell` ensures the migration completes without leaving stray configuration files in the active theme.

## Frequently Asked Questions

### What happens if I keep both alacritty.toml and colors.toml in my theme?

If both files exist, Omarchy will stage the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) as the palette source but will not overwrite a manually provided [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml). However, this creates maintenance overhead since the terminal configuration won't update automatically when you modify the palette. The recommended approach is to remove [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) and let Omarchy generate it from the template.

### Does Omarchy support light mode in colors.toml?

Yes, the [`colors.toml`](https://github.com/omacom/omarchy/blob/main/colors.toml) schema supports a `mode` key that accepts `"dark"` or `"light"` values. When creating your migration file, set `mode = "light"` for light themes. Omarchy uses this value to adjust generation logic where applications support distinct light and dark variants.

### How do I verify that my legacy alacritty.toml isn't being staged?

Run the shell test suite with `./test/shell` and examine the theme staging tests in [`test/shell.d/theme-staging-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/theme-staging-test.sh). These tests verify that legacy files like [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml) are excluded from the staged theme directory. If the `assert_no_marker alacritty.toml` assertion passes, your migration is clean and the legacy file is not being copied to `~/.local/state/omarchy/current/theme/`.

### Can I customize the generated alacritty.toml template?

While you can edit `default/themed/alacritty.toml.tpl` to change how Omarchy generates terminal configurations for all themes, this affects the entire system. For theme-specific customizations, you would need to ship a custom [`alacritty.toml`](https://github.com/omacom/omarchy/blob/main/alacritty.toml), though this prevents the theme from benefiting from future template updates in the Omarchy core.