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

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:

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

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

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

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

#!/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, 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.

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, 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.

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