OPINIONATED OMARCHY
TROUBLESHOOTING CORPUS
790
RECORDS
790
AUDITED
0
UNCHECKED
2388
SOURCES
LIVE
hyprland-config high common DISPUTE

Rebuild hyprpm plugins after a Hyprland update breaks the headers

hyprlandarchendeavouroscachyosmanjaroomarchy
CORRECTED An auditor found the fix wrong or incomplete and rewrote it.
AUDIT NOTE

Checked on this workstation, omarchy 4.0.2-1 and hyprland 0.56.2-1, plus the Hyprland v0.56.2 source. The headline claim holds: plugins are built against one exact Hyprland build and src/plugins/PluginSystem.cpp refuses a load when the plugin's API version does not match HYPRLAND_API_VERSION, while hyprpm/src/core/PluginManager.cpp headersValid() compares the headers' GIT_COMMIT_HASH against the running commit and a stored ABI hash against the running ABI string. Three things were wrong for Omarchy 4 and Hyprland 0.56.2. First, the cleanup command is dead: hyprpm/src/core/DataState.cpp puts the state at /var/cache/hyprpm/<username> with headers in headersRoot, so rm -rf ~/.local/share/hyprpm ~/.cache/hyprpm removes nothing, and confirmed on this machine that neither path exists while /usr/bin/hyprpm is present and owned by hyprland 0.56.2-1. The replacement is hyprpm purge-cache, which hyprpm --help on the installed binary lists and which hyprpm itself recommends in its own error output. Second, the quoted symptom strings are stale: pkexec is gone from hyprpm, hyprpm/src/helpers/Sys.cpp now uses sudo, doas or run0, and the current text is Headers corrupted. Please run hyprpm update to fix those. The 2023 issue 4284 documented the pkexec wording and no longer describes anything 0.56.2 emits, so it is removed. failed to install headers with error code 2 does still exist and issue 5896 stays. Third, the autostart snippets were unlabelled: Omarchy 4 is Lua and its own /usr/share/omarchy/default/hypr/autostart.lua uses exactly hl.on("hyprland.start", function() hl.exec_cmd(...) end), so both branches are now labelled and the user file named as ~/.config/hypr/autostart.lua. Added the Omarchy 4 fact that matters most: hyprpm appears nowhere in /usr/share/omarchy and nowhere in the omacom/omarchy quattro tree (GitHub code search returned 0), so omarchy update does nothing about plugins, and the similarly named omarchy plugin / omarchy-plugin-update commands manage Quickshell QML plugins under ~/.config/omarchy/plugins/ and are a different system entirely. The build-dependency line was checked against /usr/bin/omarchy-update-pacman-guard and is safe: the guard only aborts when both -S and -u are present, so pacman -S --needed passes. Frequency lowered from very-common to common, because on Omarchy 4 there is no shipped plugin story at all and users are steered to the shell plugin system instead. NOT exercised: no plugin was installed, so hyprpm add, hyprpm update, hyprpm list and hyprpm reload were not run on this machine, per the read-only rule.

The cause above was rewritten on 2026-09-13 to match this note; the fix was corrected by the audit itself.
RISK

Plugins run inside Hyprland as native code. A bad one can crash the whole graphical session and take unsaved work in every open window with it, and a malicious one can do anything your user can. Read the source of any plugin before enabling it, and never load a .so someone sent you. Hyprland's plugin-unload-on-crash protections are best effort, not guaranteed. hyprpm update and hyprpm purge-cache escalate to root with sudo, doas or run0 to write under /var/cache/hyprpm, so be sure what you are running before you type the password.

Symptom

After a Hyprland update, plugins stop loading. hyprpm reload prints <plugin> will be loaded after restarting Hyprland, or hyprpm update fails with failed to install headers with error code 2 or Headers corrupted. Please run hyprpm update to fix those. hyprctl plugin list reports no plugins loaded and the plugin keybinds do nothing. The Hyprland log records Plugin <path> could not be loaded. (API version mismatch).

Cause

Hyprland plugins are C++ shared objects compiled against the exact Hyprland build they will run inside, and there is no stable ABI. On load, Hyprland reads the plugin's reported API version and refuses anything that does not match its own HYPRLAND_API_VERSION, logging Plugin <path> could not be loaded. (API version mismatch). Every Hyprland version bump therefore invalidates every installed plugin until it is rebuilt. hyprpm keeps its own header tree and validates it two ways: it compares the GIT_COMMIT_HASH in the installed version.h against the running Hyprland's commit hash, and a stored ABI hash against the running Hyprland's ABI string, the value hyprctl version prints as Version ABI string. A mismatch in either means the headers must be re-fetched and the plugins rebuilt. On Hyprland 0.56.2 that header tree is at /var/cache/hyprpm/<username>/headersRoot and is root owned, not in your home directory, so hyprpm escalates with sudo, doas or run0 to write it. Omarchy 4 plays no part: hyprpm ships inside the hyprland package at /usr/bin/hyprpm and nothing in Omarchy calls it, so omarchy update upgrades Hyprland and leaves stale plugins behind.

Fix

Rebuild the plugins against the new headers every time Hyprland changes version.

Install the build dependencies first. This is a plain install with no database refresh, so Omarchy's ALPM guard does not block it. The guard in /usr/bin/omarchy-update-pacman-guard only aborts when both -S and -u are present:


sudo pacman -S --needed cpio cmake git meson gcc

Then rebuild and reload:


hyprpm update       # re-fetch the headers for the running Hyprland and rebuild every plugin
hyprpm list         # confirm each plugin is enabled and was built
hyprpm reload -n    # load them, with a notification

If hyprpm reload prints <plugin> will be loaded after restarting Hyprland, the running compositor does not match what the plugin was built against. Run hyprpm update first, then log out and back in.

If the headers are wedged, reset hyprpm completely. On Hyprland 0.56.2 the hyprpm state lives in /var/cache/hyprpm/<username> and is root owned, so deleting ~/.local/share/hyprpm or ~/.cache/hyprpm does nothing at all. Use the built-in command, which escalates with sudo, doas or run0 and will prompt for your password:


hyprpm purge-cache
hyprpm add https://github.com/hyprwm/hyprland-plugins
hyprpm enable hyprexpo
hyprpm update && hyprpm reload

Make the plugins load at every startup.

Omarchy 4 and any Hyprland 0.55 or newer use Lua. Put this in ~/.config/hypr/autostart.lua, which is the file Omarchy reserves for your own startup commands:


hl.on("hyprland.start", function() hl.exec_cmd("hyprpm reload -n") end)

Older Hyprland on hyprlang config, in hyprland.conf:


exec-once = hyprpm reload -n

If Hyprland now crashes on start, the plugin is the cause. Disable it from a TTY:


hyprpm disable <plugin-name>

Manual plugins that do not go through hyprpm need sudo make installheaders from a Hyprland checkout at your exact version, then hyprctl plugin load /absolute/path/to/plugin.so. The path must be absolute.

Omarchy 4 note. omarchy plugin ... and omarchy-plugin-update are a different system and will not help here. They manage QML plugins for omarchy-shell under ~/.config/omarchy/plugins/, which are Quickshell code with no connection to hyprpm or to Hyprland C++ plugins. There is no reference to hyprpm anywhere in /usr/share/omarchy or in the omacom/omarchy quattro tree, so omarchy update upgrades Hyprland and leaves your plugins stale. Running hyprpm update afterwards is on you.

Verify

hyprctl plugin list names the plugin instead of printing no plugins loaded, and hyprpm list shows it enabled with no version mismatch. hyprpm update completing without a failed to install headers or Headers corrupted line means the header tree now matches the commit hash and ABI string that hyprctl version reports.

Sources

hyprpm-plugins-broken-after-hyprland-update