How to find, install, update and remove Omarchy plugins
The whole Omarchy desktop is built from shell plugins, and a handful of omarchy plugin commands let you add, swap, clone and remove them. Here’s the full workflow, plus the security caveats worth knowing first.
Image: Omarchy (omarchy.org)
On Omarchy, plugins aren’t bolted on afterwards. They are the desktop. According to the Shell Plugins chapter of the Omarchy manual, everything runs in a single long-lived Quickshell process called omarchy-shell, and the bar, its drop-down panels, the Omarchy menu and the lock screen are all plugins inside it. The built-ins live in $OMARCHY_PATH/shell/plugins/, and anything you add goes in ~/.config/omarchy/plugins/. The commands below are already in the current stable release, Omarchy 4.0.6 (we checked its source), so you don’t need the 4.5 release candidate to use them.
Find plugins. The marketplace is plugins.omarchy.org, linked from the Omarchy site and the manual, where you can browse community plugins, read the source and copy the install command. To see what’s already on your machine, run omarchy plugin list (add --json for scripts). It shows each plugin’s id, whether it’s enabled, whether it’s first-party or third-party, and its kinds. Built-in ids all start with omarchy., and that prefix is reserved, so a third-party plugin can’t pose as one.
Turn plugins on and off. Built-ins can be toggled with omarchy plugin enable omarchy.tailscale or omarchy plugin disable omarchy.weather. If you’d rather use the menu, the manual points to Setup > Plugins, which offers Enable, Disable, Add, Clone and Remove. Your choices are saved in ~/.config/omarchy/shell.json.
Install a plugin. A third-party plugin is just a git repo with a manifest.json at its root. Install it with omarchy plugin add <git url> --enable. First it warns you that plugins run as unsandboxed code inside your shell, shows you the URL and asks you to confirm. It then clones the repo, validates the manifest and refuses the install if another plugin already uses that id. The manual is clear that it never runs anything from the plugin, never executes an install hook and never asks for sudo. Leave out --enable and it asks whether to switch the plugin on, so you can say no and read the code first.
Update and remove. omarchy plugin update <id> updates one plugin, and omarchy plugin update with no id updates every git-managed plugin. It shows you the diff before applying it, refuses to update if you have local changes it can’t fast-forward past, and rolls back if the new revision fails validation. omarchy plugin remove <id> disables the plugin and then deletes its git checkout, since the repo still exists upstream. A hand-made folder with no git repo isn’t deleted. It’s moved to a timestamped backup inside the plugins directory.
Tweak a built-in without forking Omarchy. Don’t edit files under $OMARCHY_PATH, because the next update overwrites them. Run omarchy plugin clone omarchy.clock instead. It copies the plugin to ~/.config/omarchy/plugins/<username>.clock, enables your copy and switches the shell over to it. Add --edit to open it in $EDITOR right away. Saving a file in the plugins directory reloads the plugin automatically, and removing the clone brings the built-in back.
Read the security fine print. The manual says plugin code runs “with everything your user account can reach”, so only add repos you’re willing to run. The marketplace README adds that its automated checks “are not a security audit”. It also says the current install and update commands pull the repo’s latest upstream code rather than the exact commit the marketplace reviewed: they “clone mutable upstream HEAD and are not verification-bound.” The community has started building tools for this: mattwolfgang’s omarchy-plugin-guard security-checks a plugin before you install or update it, and haplo’s omarchy-plugin-gate is a review-before-update gate.
Write and share your own. A plugin is a folder with some QML and a manifest.json declaring schemaVersion: 1, an id, name, version, its kinds and entryPoints. The kinds are bar-widget, panel, overlay, menu, service and bar. Run omarchy plugin validate ./my-plugin to get the same checks the shell runs at load time, then push it to a public git repo. To get it listed, use the marketplace’s plugin submission form. Every new listing needs a fresh scan of the exact commit and an explicit approved-and-verified decision from a maintainer before it goes live.
