Installation
hyprpm
hyprpm is the primary non-Nix installation path.
On Arch Linux, hyprpm is a separate package. Upgrading hyprland alone may leave the manager command unavailable. Install it before registering the plugin:
sudo pacman -S hyprpmhyprpm add https://github.com/sandwichfarm/hyprexpo
hyprpm enable hyprexpo
hyprpm reloadThe plugin repository is named hyprexpo in hyprpm.toml, and the built output is hyprexpo.so.
When registering from a source checkout, use the guarded wrapper:
./scripts/hyprpm-add.sh https://github.com/sandwichfarm/hyprexpoIt also accepts a revision argument for the development track. Before invoking hyprpm, an explicit revision is checked in a fresh clone against maintained branch or release-tag history. A temporary PR branch or a PR-only commit is rejected. A locally available commit is not sufficient: squash merges can leave it unavailable to a future normal clone.
After Upgrading Hyprland
Start the updated Hyprland session, then rebuild and reload the managed plugins against that running version:
hyprpm update &&
hyprpm reload &&
hyprctl reloadRun hyprpm as your normal user in a terminal and authenticate its sudo prompt when it installs headers. Run only one hyprpm update process at a time; updates share a staging directory. If a command fails, resolve the error before reloading. For a checkout failure, see the full-history retry.
Confirm that hyprexpo appears in the loaded-plugin list and check for errors:
hyprctl plugin list
hyprctl configerrorsIf the plugin is absent and existing options become unknown, follow missing-plugin recovery.
Build From Source
Build dependencies are a C++23 compiler, pkg-config, Hyprland development headers, and these pkg-config packages:
hyprland hyprgraphics pixman-1 libdrm pangocairo libinput libudev wayland-server xkbcommon luaThe current Hyprland 0.57 target requires Lua 5.5 (>=5.5, <5.6). Make, CMake, and Meson try the pkg-config modules lua, lua5.5, lua55, lua-5.5, and lua-55, accepting only that version range. This prevents an installed Lua 5.4 development package from silently selecting the wrong ABI. The dependency must match the Lua runtime in the target Hyprland build.
For a distribution-specific module name, select it explicitly with make LUA_PKG_CONFIG=<module>, cmake -DHYPREXPO_LUA_PKG_CONFIG=<module>, or meson setup -Dlua_pkg_config=<module>. Overrides must also identify Lua 5.5; an incompatible or missing module stops the plugin build with an error.
Build with the Makefile:
git clone https://github.com/sandwichfarm/hyprexpo
cd hyprexpo
make allAlternative build entry points are available:
meson setup build
meson compile -C buildcmake -S . -B build
cmake --build buildInstall a Local Build
For development, do not replace the hyprpm-managed copy first. Hyprland's plugin development docs recommend testing in a nested debug session and loading the built plugin by absolute path with hyprctl plugin load.
Launch a disposable nested session that builds and loads a user-owned local plugin artifact:
./scripts/run-nested.shIf you already have a disposable Hyprland session running, build to ${XDG_CACHE_HOME:-$HOME/.cache}/hyprexpo/hyprexpo.so and load or reload it:
make dev-load
make dev-reloadOnly replace the hyprpm-managed copy when you intentionally want the installed plugin to point at this checkout's build:
make install
hyprpm reloadmake install and scripts/dev-link.sh check the saved repository.rev before changing a managed destination. The preflight uses Git and Python 3.11+ and requires network access only for an explicit revision. Run it independently with make check-hyprpm-state (INSTALL_USER and INSTALL_DIR select the same destination as make install). Failed or unreadable state stops replacement; see saved-revision recovery. These commands never persist a test revision. Use the development load commands above for PR testing.
If the hyprpm artifact path is root-owned, keep the privilege at the command line and preserve the target user explicitly:
sudo make install INSTALL_USER="$USER"
hyprpm reloadEquivalent manual install:
make check-hyprpm-state &&
install -Dm755 hyprexpo.so \
"/var/cache/hyprpm/$USER/hyprexpo/hyprexpo.so"
hyprpm reloadUse sudo install ... only if that destination is intentionally root-owned.
WARNING
Use install, not plain cp, when replacing a loaded .so. Hyprland maps the plugin into the running process. Overwriting that file in place can corrupt the live mapping and crash the session.
Nix
Nix users should build HyprExpo through the Nix Hyprland plugin path instead of mixing a hyprpm artifact into a Nix-managed Hyprland session. The repository contains default.nix, which uses hyprlandPlugins.mkHyprlandPlugin so the plugin follows the Hyprland input supplied by the caller.
Hyprland plugins are ABI-sensitive. Keep the plugin build and running Hyprland revision aligned. If Hyprland is updated, rebuild HyprExpo from the same Hyprland input before loading it.