Omarchy Plugins: Install, Update, and Stay Safe

Learn how to find, install, enable, update, and remove Omarchy Quattro shell plugins, including the security risks of unsandboxed third-party QML code.

Omarchy Quattro models bar widgets, panels, menus, overlays, and background services as Shell Plugins. Plugins can extend the desktop, but a third-party plugin is not a static theme or a sandboxed browser extension. It runs QML and code with your user permissions inside the long-lived shell process.

A plugin is third-party code

Omarchy's manual says third-party plugins are unsandboxed and can access everything your user account can access. Review the author, repository, license, source, and recent commits before installation. Avoid unknown plugins on a production machine.

List, enable, and disable plugins

List available plugins first:

omarchy plugin list

Enable or disable an installed plugin:

omarchy plugin enable omarchy.tailscale
omarchy plugin disable omarchy.weather

First-party plugins live in $OMARCHY_PATH/shell/plugins/; user plugins live in ~/.config/omarchy/plugins/. Enabled state is stored in ~/.config/omarchy/shell.json. Back up your user configuration and do not edit the first-party directory in place.

Install a community plugin from Git

The official CLI can clone a repository and validate its manifest:

omarchy plugin add https://github.com/acme/omarchy-weather.git --enable

--enable turns it on after installation. The installer clones and validates the manifest without running install hooks or using sudo, but validation is not a security audit. The plugin still executes after it is enabled.

The community Omarchy Plugins directory can help with discovery; inclusion is not a security endorsement. Before installing, check:

whether the repository URL matches the author's public identity;
whether it has a readable license, README, and change history;
whether QML or scripts read secrets, browser data, SSH files, or launch commands;
whether maintainership or code style changed unexpectedly;
whether you can test it under a disposable account or non-production device.

Update, inspect changes, and recover

Update one plugin or every installed plugin:

omarchy plugin update acme.weather
omarchy plugin update

The official update flow shows a diff, requires a fast-forward update, and rolls back a version that fails validation. Those safeguards reduce accidental breakage; they do not determine whether new code is trustworthy. Read the diff and disable a suspect plugin before further diagnosis:

omarchy plugin disable acme.weather

Remove it when it is no longer needed:

omarchy plugin remove acme.weather

If the shell cannot start, use a TTY or recovery environment to back up ~/.config/omarchy/shell.json, then move the suspect user plugin out of the plugin directory. Do not erase the whole configuration without a backup.

Develop or customize a plugin

Clone a first-party plugin as a starting point and validate a local directory:

omarchy plugin clone omarchy.clock
omarchy plugin validate ./my-plugin

The current manifest uses schemaVersion: 1 and QML entry points. Supported kinds include bar-widget, panel, overlay, menu, service, and bar. Interfaces can change with releases, so verify against the current Shell Plugins manual before publishing.

What to verify after enabling a plugin

The bar, notifications, lock screen, and quick menus still open.
Shell CPU, memory use, and logs remain normal.
A network or service outage does not block the desktop.
Updates do not add unexpected permissions, requests, or commands.
Disabling the plugin removes the observed problem.

For the release that introduced this architecture, read the Omarchy Quattro 4.0 guide. If the desktop breaks, preserve logs and isolate changes with the troubleshooting guide.

Sources: official Omarchy Shell Plugins manual and Omarchy v4.0.0 release notes.