Installation

hyprpm

hyprpm is the primary non-Nix installation path.

hyprpm add https://github.com/sandwichfarm/hyprexpo
hyprpm enable hyprexpo
hyprpm reload

The plugin repository is named hyprexpo in hyprpm.toml, and the built output is hyprexpo.so.

Build From Source

Build dependencies are a C++23 compiler, pkg-config, Hyprland development headers, and these pkg-config packages:

hyprland pixman-1 libdrm pangocairo libinput libudev wayland-server xkbcommon lua5.4

The build prefers the lua5.4 pkg-config module and falls back to lua for distributions such as Fedora where lua-devel exposes the generic module name.

Build with the Makefile:

git clone https://github.com/sandwichfarm/hyprexpo
cd hyprexpo
make all

Alternative build entry points are available:

meson setup build
meson compile -C build

cmake -S . -B build
cmake --build build

Install 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.sh

If 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-reload

Only replace the hyprpm-managed copy when you intentionally want the installed plugin to point at this checkout's build:

make install
hyprpm reload

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 reload

Equivalent manual install:

install -Dm755 hyprexpo.so \
    /var/cache/hyprpm/$USER/hyprexpo/hyprexpo.so
hyprpm reload

Use 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.