hyprland-plugins: Installation and Plugin Boundaries

The four-plugin scope of hyprland-plugins

hyprland-plugins solves a small set of Hyprland customization problems. It is aimed at Hyprland users who want additional window decoration, native-looking title bars, a focus effect, or a fix for custom resolutions in CS:GO when Vulkan is selected. The repository is not a general-purpose collection of Hyprland utilities. Its plugin list contains four entries: `borders-plus-plus`, `csgo-vulkan-fix`, `hyprbars`, and `hyprfocus`.

Each entry has a sharply defined purpose. `borders-plus-plus` adds one or two additional borders to windows. `hyprbars` adds title bars. `hyprfocus` provides a `flashfocus` effect for Hyprland. `csgo-vulkan-fix` addresses custom resolutions in CS:GO when launched with `-vulkan`. That narrow catalog is useful because it lets engineers judge the repository by concrete behavior instead of assuming that every issue belongs in a plugin collection.

The directory layout supports that interpretation. Each named plugin has its own subdirectory, and the README directs users to the respective subdirectory README for configuration options. The repository also includes `CMakeLists.txt`, `flake.nix`, `flake.lock`, `.clang-format`, and `hyprpm.toml`. This is a C++ build and packaging project with a Nix package definition, rather than a configuration repository containing Hyprland settings by itself.

Why plugin and Hyprland version alignment matters

The central installation constraint is compatibility between the plugin build and the Hyprland version loaded at runtime. The repository states that its officially supported installation method is `hyprpm`. According to the README, `hyprpm` detects the user's Hyprland version and installs the corresponding pinned release of `hyprland-plugins`. This is more restrictive than always building the latest branch, but it gives users a documented relationship between the installed compositor version and the plugin artifacts.

The distinction matters if you want newer commits. The README explicitly says that obtaining the latest commits requires `hyprland-git`. That wording separates ordinary version-aligned plugin installation from development against a Hyprland build obtained from Git. It does not document compatibility guarantees for arbitrary commit combinations, so treating `main` as interchangeable with a pinned release would go beyond the README.

The repository is not archived, and its last push was on 2026-10-07. It also has no GitHub releases. The README nevertheless refers to corresponding pinned releases managed by `hyprpm`, so users should not equate the absence of a GitHub releases listing with an absence of version selection. The repository does not explain how `hyprpm` maps Hyprland versions to commits, nor does it publish a compatibility matrix. That implementation detail would need to be checked through `hyprpm` itself.

Installing a first plugin through hyprpm

The documented `hyprpm` route is the clearest first-use path for a normal Hyprland installation. Start by updating `hyprpm` so it can perform repository and version-aware plugin management:

hyprpm update

The command should complete without an installation error. The README does not document its output, so specific success text cannot be confirmed.

Next, add the official plugin repository:

hyprpm add https://github.com/hyprwm/hyprland-plugins

This tells `hyprpm` where the repository is located. Then enable the plugin whose documented behavior you want. For example, `hyprbars` adds title bars to windows:

hyprpm enable hyprbars

The repository's general form is `<plugin-name>`, but `hyprbars` is one concrete entry from the documented plugin list. Replace it only with `borders-plus-plus`, `csgo-vulkan-fix`, or `hyprfocus` when one of those plugins is the intended target.

After enabling the desired plugin, consult that plugin's README for configuration keys. The top-level README does not provide those keys or document a universal reload command for an arbitrary installed plugin. As a result, the exact configuration example and runtime verification step for `hyprbars` must come from its subdirectory README rather than being guessed.

Nix builds for locked Hyprland inputs

The Nix path targets users who already use the Hyprland flake. Its key design choice is the `inputs.hyprland.follows` relationship. The README says this makes the plugins build with the locked Hyprland version and prevents version mismatches that could lead to errors. That approach aligns the source input used for plugins with the compositor input selected by the user.

There are two documented integration paths. The first uses the Home Manager module and selects packages from `inputs.hyprland-plugins.packages` using `pkgs.stdenv.hostPlatform.system`. The listed Home Manager example includes `hyprbars` in `wayland.windowManager.hyprland.plugins`. This form lets Home Manager own the plugin configuration as part of the Hyprland module.

The second path constructs a plugin directory with `pkgs.symlinkJoin` and exports it as `HYPR_PLUGIN_DIR`. The README then directs users to load an installed shared object from `hyprland.conf` with `hyprctl plugin load`. Its example names `lib/libhyprexpo.so`, so that path is an example for `hyprexpo`, not a universal filename for all four plugins.

This Nix coverage is more specific than the `hyprpm` instructions. It documents input alignment and two deployment styles, but it does not explain automated upgrades, plugin rollback, or compatibility testing for individual plugin versions. Those maintenance operations cannot be inferred from the flake inputs.

Plugin loading and configuration ownership

The documented architecture separates plugin acquisition from runtime loading. With `hyprpm`, the plugin manager detects Hyprland, selects a matching pinned plugin release, and enables the requested plugin. With the Nix setup that does not use Home Manager, the flake packages are joined into a plugin directory, `HYPR_PLUGIN_DIR` points to that directory, and a Hyprland configuration invokes `hyprctl plugin load` for a shared object.

This separation has an operational consequence. Installing or enabling a plugin does not by itself supply every configuration key. The top-level README sends users to each plugin's README for configuration options. Configuration ownership stays close to each plugin rather than being centralized in the top-level installation guide.

The four plugins also sit at different levels of the desktop experience. Window border and title-bar plugins affect normal window presentation. `hyprfocus` supplies focus feedback. `csgo-vulkan-fix` targets one game configuration issue and is not a general Vulkan compatibility layer. Treating all four as a single preset would hide those boundaries. Engineers evaluating the repository should select an individual plugin and then read its own configuration documentation.

Limits of the documented plugin catalog

The clearest limitation is catalog size. The repository lists four plugins and does not claim to cover broader Hyprland customization, plugin discovery, lifecycle management, or general troubleshooting. `hyprpm` performs repository management, but it is an external tool rather than a plugin included by this repository. The README does not document what happens if a plugin conflicts with another border or title-bar implementation, so users should not assume that multiple decorative plugins can safely be enabled together.

There is also a version boundary. The supported `hyprpm` path installs a pinned release corresponding to the detected Hyprland version, while the latest commits are tied to use with `hyprland-git`. The README does not promise that plugins from `main` work with every release. It also does not document a rollback command after enabling an unsuitable plugin.

A related gap is troubleshooting. The top-level README links to the plugins wiki and recommends `hyprpm -h`, but it does not provide diagnostic output, log paths, test cases, or failure messages for failed plugin loading. Based on the repository layout, each plugin can have its own README, so detailed behavior may exist below the top level. It cannot be assigned to the wrong plugin or represented as a documented support promise without reading that plugin's documentation.

License, maintenance, and upgrade boundaries

The repository identifies the primary language as C++ and the license as `BSD-3-Clause`. That designation is relevant when reviewing redistribution or integration obligations, but this article does not interpret the license text or provide legal advice. The README does not add a plugin-specific licensing section, so separate licensing terms should not be assumed for game files, external assets, or dependencies unless their own documentation states them.

The repository is not archived, and the last push was on 2026-10-07. There are no GitHub releases. For ordinary installation, `hyprpm` handles version-aligned pinned selection, which reduces the need to manually track plugin commits. For Nix users, the flake lock participates in input and package selection, but the README does not document an upgrade or rollback sequence.

The actual cost of changing versions therefore depends on the installation route. `hyprpm` users rely on its detection and pinning behavior. Nix users must account for the locked Hyprland input and package selection. Users seeking latest commits accept a `hyprland-git` workflow outside the repository's ordinary pinned-release path. Before upgrading, inspect `hyprpm -h` or the plugin-specific README because the top-level README does not enumerate supported upgrade flags or recovery steps.

Editorial conclusion

Adopt this repository if you need one of its four documented Hyprland plugins and use the installation route that matches your Hyprland version. Do not expect it to provide a general plugin framework, configuration reference, or rollback procedure. Verify first that `hyprpm update` succeeds, that the selected plugin matches the installed Hyprland release, and that its subdirectory README documents every setting you intend to change.

Frequently asked questions

Official sources

1. hyprwm/hyprland-plugins on GitHub
2. Issues
3. License: BSD-3-Clause
4. README