# How to Update Omarchy Themes: A Complete Guide to Managing Extra Themes

> Easily update your installed Omarchy themes with our comprehensive guide. Learn how to manage extra themes and keep your customizations current using the omarchy-theme-update command.

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

---

**Run `omarchy-theme-update` to pull the latest changes for all user-installed themes stored in `$HOME/.local/state/omarchy/current/theme`.**

Omarchy stores user-installed themes as individual Git repositories, making it straightforward to track upstream changes and sync improvements. Whether you are running the `basecamp/omarchy` dotfiles on a fresh installation or maintaining a long-term setup, knowing how to update Omarchy themes ensures you receive bug fixes and new features from theme authors immediately.

## Where Omarchy Stores User-Installed Themes

User-installed themes—referred to as **extra themes**—live as separate Git checkouts under:

```bash
$HOME/.local/state/omarchy/current/theme

```

Each subdirectory inside this path represents a standalone theme repository. Omarchy treats these directories as mutable, user-managed assets that remain separate from the core system defaults.

## How the omarchy-theme-update Command Works

The `omarchy-theme-update` script provides a safe, automated wrapper around standard Git operations. Located at `bin/omarchy-theme-update` in the repository, the script handles discovery and synchronization without manual intervention.

### Theme Discovery

First, the script invokes `omarchy-theme-extras` (a helper utility at `bin/omarchy-theme-extras`) to identify all directories containing valid Git repositories:

```bash

# Lines 5-6 of bin/omarchy-theme-update

readarray -t themes < <(omarchy-theme-extras)

```

This outputs an array of absolute paths to theme directories, ensuring the update logic only targets actual extra themes and not core system files.

### Pulling Latest Changes

For each discovered theme, the script prints a status line and executes a **pull** operation:

```bash

# Lines 7-10 of bin/omarchy-theme-update

for theme in "${themes[@]}"; do
  echo "Updating: $(basename "$theme")"
  git -C "$theme" pull
done

```

The `git -C "$theme" pull` command fetches and merges upstream changes while preserving any local customizations that do not conflict with remote updates.

## Updating Themes via the GUI Menu

You can trigger the update routine directly from the Omarchy interface. The menu definition in `default/omarchy/omarchy-menu.jsonc` maps the **Update → Extra Themes** entry to the `"update.themes"` action (line 44), which executes `omarchy-theme-update` in a terminal window. This provides a point-and-click method to update Omarchy themes without opening a shell manually.

## Manual Theme Updates and Custom Scripts

While `omarchy-theme-update` handles bulk operations, you can update individual themes manually for debugging or selective synchronization:

```bash

# Update a specific theme (replace <path> with output from omarchy-theme-extras)

git -C ~/.local/state/omarchy/current/theme/Tokyo\ Night pull

```

For automation hooks—such as running theme updates after a system-wide package upgrade—integrate the command into a custom Bash script:

```bash
#!/usr/bin/env bash

# Refresh all extra themes after system maintenance

omarchy-theme-update || echo "Theme update failed" >&2

```

This pattern is validated by the test suite in [`test/shell.d/theme-staging-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/theme-staging-test.sh), which covers the Git pulling logic to ensure reliability across different shell environments.

## Summary

- **Storage Location**: Extra themes reside in `$HOME/.local/state/omarchy/current/theme` as Git repositories.
- **Primary Command**: `omarchy-theme-update` automates discovery and synchronization of all extra themes.
- **Implementation**: The script uses `bin/omarchy-theme-extras` to list themes, then runs `git pull` in each directory (as seen in `bin/omarchy-theme-update` lines 7-10).
- **GUI Access**: Available via the **Update → Extra Themes** menu entry defined in `omarchy-menu.jsonc`.
- **Documentation**: Comprehensive theming guides are available in [`docs/theming.md`](https://github.com/basecamp/omarchy/blob/main/docs/theming.md).

## Frequently Asked Questions

### Where are Omarchy themes stored on disk?

Extra themes are stored as Git repositories in `$HOME/.local/state/omarchy/current/theme`. Each subdirectory represents a single theme that tracks its own upstream remote independently of the core Omarchy system.

### Can I update a single theme instead of all at once?

Yes. While `omarchy-theme-update` refreshes every extra theme automatically, you can target a specific theme by running `git -C <theme-path> pull` manually. Use `omarchy-theme-extras` to identify the correct `<theme-path>` for the theme you wish to update.

### What Git command does omarchy-theme-update use internally?

According to the `basecamp/omarchy` source code, the script executes `git -C "$theme" pull` for each discovered theme directory. This fetches and merges changes from the remote repository while operating within the theme's specific directory context.

### Is there a way to test the theme update mechanism?

The repository includes [`test/shell.d/theme-staging-test.sh`](https://github.com/basecamp/omarchy/blob/main/test/shell.d/theme-staging-test.sh), which contains tests for the theme pulling logic. You can review or run this test suite to verify that the update mechanism behaves correctly on your system before relying on it in production workflows.