How to Install and Manage Omarchy Plugins & Themes (2026)

✅ Tested on Omarchy v4.0.0 “Quattro” · Arch Linux · omarchy-shell — Last updated: August 2026

Omarchy runs its entire desktop as a single long-lived Quickshell process called omarchy-shell. Almost everything you see on screen — the bar, the launcher, the notification popups — is a plugin inside it. That's not a marketing line, it's the literal architecture, and it's why themes and widgets in Omarchy install and update completely differently from a typical Linux desktop.

This guide covers the real plugin system: the six plugin types, where they live on disk, the official omarchy plugin commands, and how to find and install community themes and widgets from omarchyplugins.com and GitHub. If you haven't installed Omarchy yet, start with the install guide; if you're deciding whether Omarchy is worth it at all, read the full review first.

What a Plugin Actually Is in Omarchy

A plugin is a folder with a manifest.json file and one or more QML entry points. There's no separate "theme engine" bolted on top — a visual theme is just a plugin, usually of kind bar or bar-widget, that changes what omarchy-shell renders. That single-process design is also why Quattro (the August 2026 rewrite) replaced eight separate background processes — Waybar, Walker, Mako, SwayOSD, hyprlock, hypridle, swaybg, polkit-gnome — with one: fewer moving parts, one plugin API instead of eight config formats.

Every plugin declares a kind in its manifest, and the kind determines how it slots into the shell:

A single plugin can declare more than one kind if it needs to (a theme pack, for example, might ship a bar plus several bar-widget entries).

Where Plugins Live

Omarchy separates plugins into two locations, and the distinction matters if you're debugging why something isn't showing up:

• First-party: $OMARCHY_PATH/shell/plugins/ — ships with Omarchy itself, updated with the base system
• Third-party: ~/.config/omarchy/plugins/ — anything you install yourself, survives Omarchy updates

Anything you clone from GitHub or download from a marketplace goes in your ~/.config/omarchy/plugins/ folder as its own subdirectory containing a valid manifest.json.

Step 1 — List What's Already Installed

Before installing anything new, see what Omarchy already discovers on your system:

omarchy plugin list
# or, for scripting / piping into jq
omarchy plugin list --json

This shows every plugin Omarchy can see in both the first-party and third-party directories, along with whether each one is currently enabled.

Step 2 — Install a Third-Party Plugin or Theme

Community plugins are distributed as git repositories. The official way to install one is:

omarchy plugin add https://github.com/<author>/<repo> --enable

This clones the repo straight into ~/.config/omarchy/plugins/ and enables it in one step. Drop --enable if you want to inspect the plugin first before turning it on.

A few active community repos worth browsing for real examples of the manifest format and QML structure:

• brianblakely/omarchy-plugins — storefront-style collection of widgets and features
• bjarneo/omarchy-shell-plugins — includes the Omni command palette plugin
• forbidden-game/omarchy-plugins — curated high-efficiency bar widgets
• awesome-omarchy — not a plugin itself, but a curated list of Omarchy resources, themes, and plugins worth checking before you start hunting on GitHub yourself

Step 3 — Enable, Disable, and Update Plugins

Once a plugin is on disk, you control it with these commands:

omarchy plugin enable <id>      # turn a plugin on
omarchy plugin disable <id>     # turn a plugin off without removing it
omarchy plugin update            # pull the latest changes for all git-based plugins
omarchy plugin update <id>      # update just one
omarchy plugin remove <id>      # delete a plugin entirely

The <id> is the identifier declared in the plugin's own manifest.json, not the folder name or the GitHub repo name — run omarchy plugin list first if you're not sure what ID a plugin registered itself under.

Step 4 — Find Themes on omarchyplugins.com

omarchyplugins.com is an independent community marketplace for Omarchy plugins — it's explicit on the site that it's "not affiliated with, sponsored by, or endorsed by Omarchy or 37signals." It's built for browsing: search by name, tag, or author, sort by date, popularity, or downloads, and inspect a plugin's source before installing it. There's also a "Publish a plugin" path with its own GitHub repo for contributors who want to submit their own.

Be aware it's early. As of this writing the marketplace is freshly launched with very few listed community plugins — GitHub search and the awesome-omarchy list above are currently more productive ways to find themes than the marketplace itself. That will likely change fast: Quattro is only a few weeks old and the plugin ecosystem is still forming. Worth bookmarking and checking back on.

Step 5 — Build Your Own Plugin

If nothing existing does what you want, cloning a built-in plugin as a starting point is faster than reading QML docs from scratch:

omarchy plugin clone <id> --edit

This copies one of Omarchy's own first-party plugins into your third-party directory, fully editable, and opens it for you. A minimal manifest.json needs:

{
  "schemaVersion": 1,
  "id": "your-plugin-id",
  "name": "Your Plugin Name",
  "version": "1.0.0",
  "kinds": ["bar-widget"],
  "entryPoints": {
    "bar-widget": "widget.qml"
  }
}

Before you enable anything you've hand-written, validate the manifest so a typo doesn't silently break the shell:

omarchy plugin validate ~/.config/omarchy/plugins/your-plugin-id/

If your plugin is a bar-widget, you'll also need a barWidget block in the manifest specifying its display name, category, and whether multiple instances are allowed (allowMultiple) — useful for something like a multi-monitor clock widget.

Troubleshooting Common Plugin Questions

My plugin shows up in `omarchy plugin list` but isn't visible on the bar

Check that it's actually enabled, not just discovered — being listed and being active are different states in Omarchy.

omarchy plugin enable your-plugin-id

Why did `omarchy plugin add` fail with a validation error?

The repo you cloned is missing or has a malformed manifest.json. Run the validator directly against the cloned folder to see the exact field that's wrong before opening an issue with the plugin author.

omarchy plugin validate ~/.config/omarchy/plugins/<folder-name>/

How do I go back to the stock bar after installing a `bar` replacement?

Disable the third-party bar plugin — Omarchy falls back to its first-party built-in bar automatically once no custom bar-kind plugin is active.

omarchy plugin disable your-custom-bar-id

Further Reading

• Omarchy: The Complete Guide (all posts in this cluster)
• Omarchy Review: DHH's Opinionated Arch Linux Distro for Developers
• How to Install Omarchy on Arch Linux: Complete Setup Guide
• Omarchy Keyboard Shortcuts: The Complete Hotkeys Cheat Sheet
• Omarchy vs Omakub: Which DHH Setup Should You Use?