# How to Create a Custom Omarchy Theme: Complete Guide for Beginners

> Learn to create a custom Omarchy theme by following this beginner-friendly guide. Easily set your unique color scheme and personalize your Omarchy experience.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-23

---

**Creating a custom Omarchy theme requires placing a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file inside `~/.config/omarchy/themes/<name>/` and running `omarchy theme set <name>` to generate the full configuration from templates.**

Omarchy is an opinionated Linux desktop environment developed by Basecamp that uses a simple file-based theming system. Building a custom Omarchy theme lets you define color palettes, UI overrides, and asset collections that the system compiles into active configurations. This guide walks through the exact file structure, required syntax, and activation process based on the current `basecamp/omarchy` source code.

## Where Omarchy Looks for Themes

The theming system searches for theme definitions in two distinct locations before building the active configuration.

### Stock Themes (System-Wide)

Omarchy ships with pre-built themes stored in `/usr/share/omarchy/themes/<name>/`. In the source repository, these live under the `themes/` directory and include examples like `solitude`, `retro-82`, and `lumon`. These serve as base templates that you can extend or override rather than modify directly.

### User Custom Themes (Local Configuration)

Personal themes belong in `~/.config/omarchy/themes/<name>/`. When you run `omarchy theme set <name>`, the command prioritizes files in this user directory, overlaying them on top of any stock theme with the same name. According to [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md), the system copies stock files first, then overlays your custom files, ensuring your modifications take precedence without destroying the base template.

## The Required [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) Structure

Every custom Omarchy theme **must** contain a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file at its root. This file supplies the palette keys used by built-in templates to generate application-specific configs.

The TOML file requires at minimum these keys:

```toml
mode = "dark"  # or "light"

accent = "#ff6f61"
selection = "#2c2c2c"
muted = "#44475a"

background = "#1e1e2e"
dark_background = "#14141a"
lighter_background = "#282a36"

foreground = "#f8f8f2"
bright_foreground = "#ffffff"

red = "#ff5555"
green = "#50fa7b"
blue = "#6272a4"

```

As documented in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) lines 46-71, these values drive the template engine that produces [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml), terminal configs, and window manager styles.

## Optional Overrides and Assets

Beyond the color palette, you can supply complete file replacements or additional assets that Omarchy copies verbatim during installation.

### Configuration Overrides

Place files with specific names in your theme directory to replace generated defaults:

- **[`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml)** – Replaces the entire shell color configuration.
- **[`shell.lock.toml`](https://github.com/basecamp/omarchy/blob/main/shell.lock.toml)** – Replaces only the `[lock]` section of the shell config (the filename determines the target section).
- **[`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua)** – Overrides the generated Hyprland window manager configuration.

According to [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md) lines 56-66, the staging process checks for these exact filenames and copies them instead of running the template generator.

### Asset Files

You can include static resources that Omarchy installs alongside configs:

- **`backgrounds/`** – Directory containing wallpaper images.
- **`preview.png`** – Thumbnail image displayed in theme selectors.
- **`icons.theme`** – Custom icon theme definitions.

These files live in your theme directory and copy directly to `~/.local/state/omarchy/current/theme` during activation.

## Activating Your Custom Theme

Once your files are in place, use the CLI driver to build and install the theme:

```bash
omarchy theme set my-theme

```

This command executes the logic found in `bin/omarchy-theme-set` (inspectable via `cat $(which omarchy-theme-set)`). The process follows these steps:

1. Creates a staging directory.
2. Copies the stock theme (if it exists) into the staging area.
3. Overlays files from `~/.config/omarchy/themes/<name>/`.
4. Generates missing template files (like [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) from [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml)).
5. Installs the final result to `~/.local/state/omarchy/current/theme`.
6. Signals the running shell to reload the new colors.

The change applies immediately without requiring a logout or reboot.

## Complete Example: Building a Solarflare Theme

Here is a runnable workflow to create and activate a custom theme named "solarflare":

```bash

# 1. Create the theme directory

mkdir -p ~/.config/omarchy/themes/solarflare

# 2. Write the base palette

cat > ~/.config/omarchy/themes/solarflare/colors.toml <<'EOF'
mode = "dark"

accent = "#ffb86c"
selection = "#44475a"
muted = "#6272a4"

background = "#1e1e2e"
foreground = "#f8f8f2"

red = "#ff5555"
green = "#50fa7b"
blue = "#8be9fd"
EOF

# 3. (Optional) Provide a custom shell palette

cat > ~/.config/omarchy/themes/solarflare/shell.toml <<'EOF'
[bar]
background = "{{ background }}"
foreground = "{{ foreground }}"
accent = "{{ accent }}"
EOF

# 4. (Optional) Add a background asset

mkdir -p ~/.config/omarchy/themes/solarflare/backgrounds
cp ~/wallpaper.png ~/.config/omarchy/themes/solarflare/backgrounds/

# 5. Activate the theme

omarchy theme set solarflare

```

## Summary

- **Location**: Place custom themes in `~/.config/omarchy/themes/<name>/` to override stock themes stored in `/usr/share/omarchy/themes/`.
- **Requirement**: Every theme needs a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file defining the palette keys (`accent`, `background`, `foreground`, etc.).
- **Overrides**: Add files like [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua) to replace generated configurations entirely.
- **Activation**: Run `omarchy theme set <name>` to stage, generate, and install the theme to `~/.local/state/omarchy/current/theme`.

## Frequently Asked Questions

### Where do I place files for a custom Omarchy theme?

User-created themes belong in `~/.config/omarchy/themes/<name>/`. This directory takes precedence over system stock themes located in `/usr/share/omarchy/themes/`, allowing your custom files to override default configurations without modifying system packages.

### What is the minimum file needed for a custom Omarchy theme?

You only need a [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) file containing the palette definition. The `omarchy theme set` command uses this file to generate all other necessary configuration files via templates, though you can optionally supply pre-generated files to override specific outputs.

### Can I override specific sections of generated configs rather than entire files?

Yes. Use dot-notation filenames like [`shell.lock.toml`](https://github.com/basecamp/omarchy/blob/main/shell.lock.toml) to target specific TOML sections. According to the theming documentation in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md), the filename determines which section of the generated config gets replaced, letting you override just the `[lock]` section while keeping other generated values intact.

### How does Omarchy handle missing files in a custom theme?

Missing files are generated automatically from templates during the staging process. The system copies your provided files first, then runs the template engine to create any missing configs (like [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) or [`hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/hyprland.lua)) using the [`colors.toml`](https://github.com/basecamp/omarchy/blob/main/colors.toml) palette values, ensuring a complete theme installation even with partial user input.