# How to Update Omarchy Plugins: A Complete Guide to Git-Managed Extensions > Easily update Omarchy plugins with the omarchy plugin update command. This guide shows how to perform safe Git fast-forwards from your plugin directory, preserving local changes and reviewing diffs. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: how-to-guide - Published: 2026-08-23 --- **Omarchy plugins are updated via the `omarchy plugin update` command, which performs safe Git fast-forwards from `~/.config/omarchy/plugins` while preserving local modifications and showing diffs for confirmation.** Omarchy, the extensible shell environment from Basecamp, manages plugins as Git repositories in `~/.config/omarchy/plugins`. Understanding how to update Omarchy plugins ensures you receive the latest features and security patches without overwriting your custom configurations. ## Understanding the Omarchy Plugin Update Architecture The plugin update system is implemented in `bin/omarchy-plugin-update`, which orchestrates Git operations across your local plugin directories. Although the command is marked as hidden (`# omarchy:hidden=true`) in the `GROUP_DESCRIPTIONS` table—indicating it is designed for power users and scripts—it remains fully documented in the shell README and manual pages. The system treats each plugin as an independent Git repository, allowing granular control over updates while maintaining safety guarantees that prevent accidental data loss. ## The Six-Stage Update Process When you run `omarchy plugin update`, the command executes a rigorous validation pipeline: ### 1. Plugin Discovery The command enumerates all installed plugins by reading **manifest.json** files located in `~/.config/omarchy/plugins/*/`. This discovery phase identifies which extensions are eligible for updates. ### 2. Fetching Upstream Changes For each discovered plugin, the system executes `git fetch` to retrieve the latest commits from the upstream repository. If a fetch fails, the command reports the error immediately: ```bash fetch failed for '' ``` This error handling occurs at **Line 44** of `bin/omarchy-plugin-update`, ensuring network or permission issues are surfaced before any local modifications occur. ### 3. Fast-Forward Validation Before applying changes, the command verifies that the plugin can be fast-forwarded safely. If you have uncommitted local changes, the update aborts with a clear message: ```bash cannot fast-forward ''; you have local changes in /home/user/.config/omarchy/plugins/ ``` This safety check, implemented at **Line 68**, prevents the system from overwriting your customizations. ### 4. Diff Review and Confirmation When fast-forwarding is possible, the command displays a diff between your current HEAD and the fetched upstream commits. You must explicitly confirm the update: ```text Apply this update? [y/N] ``` This interactive step ensures you review changes to files like `Panel.qml` or configuration scripts before they are applied. ### 5. Fast-Forward Execution Upon confirmation, the plugin repository is fast-forwarded to the new commit. If post-update validation fails, the system automatically rolls back the changes and reports: ```bash update of '' failed validation; rolled back ``` This rollback mechanism, found at **Line 74**, protects against corrupted or incomplete updates. ### 6. Post-Update Reload Once all plugins are processed, the Omarchy shell automatically reloads the updated extensions. New functionality appears immediately without requiring a session restart. ## Running omarchy plugin update: Command Reference The `omarchy plugin update` command supports several modes of operation: Update all installed plugins interactively: ```bash omarchy plugin update ``` Update a specific plugin by its identifier: ```bash omarchy plugin update acme.weather ``` Run updates non-interactively (automatically applies after diff review): ```bash omarchy plugin update --yes ``` ## Handling Conflicts and Local Modifications The update process respects the same safety guarantees as the core Omarchy update pipeline. The system refuses to modify any plugin that would cause a merge conflict or overwrite local customizations without explicit confirmation. If you encounter the "cannot fast-forward" error, you have two options: 1. **Commit or stash your local changes** using standard Git commands in the plugin directory, then re-run the update. 2. **Clone the plugin manually** to a different location if you intend to maintain a permanent fork. ## Summary - Omarchy plugins reside in `~/.config/omarchy/plugins` as Git-managed repositories. - The `omarchy plugin update` command automates fetching, diffing, and fast-forwarding from upstream sources. - Safety checks at **Line 44**, **Line 68**, and **Line 74** of `bin/omarchy-plugin-update` prevent data loss and handle network failures. - Updates require explicit confirmation unless using the `--yes` flag, and local changes block automatic updates to prevent overwriting customizations. - The shell automatically reloads plugins after updating, applying changes immediately. ## Frequently Asked Questions ### What happens if I have local changes in a plugin? The update command aborts with the message `cannot fast-forward ''; you have local changes in $dir`. You must commit, stash, or revert your local changes using standard Git operations in the plugin directory before the update can proceed. ### Can I update Omarchy plugins automatically without prompts? Yes. Append the `--yes` flag to `omarchy plugin update` to run non-interactively. The system will still fetch and diff changes, but will automatically confirm and apply updates. Use this flag with caution in automated scripts. ### Where are Omarchy plugins stored locally? All plugins are stored in `~/.config/omarchy/plugins/`, with each plugin occupying its own subdirectory containing a [`manifest.json`](https://github.com/basecamp/omarchy/blob/main/manifest.json) file and a full Git repository. This location is consistent across all Omarchy installations. ### What should I do if an update fails validation? If the post-update validation fails, the system automatically rolls back the plugin to its previous state and reports `update of '' failed validation; rolled back`. Check the plugin's upstream repository for breaking changes or consult the plugin's documentation for migration steps before attempting the update again.