hy3 brings i3 style tiling to Hyprland, with a tag for every Hyprland release

What the plugin adds to Hyprland

hy3 is a plugin for Hyprland that provides an i3 or sway like layout, and the feature list is four items that describe a different window management model rather than a different theme.

The first is i3 like tiling. The second is node based window manipulation, and the readme explains what that buys: you can interact with multiple windows at once, which is the operation that a manual tiling layout is built around, since a tree of splits means a set of containers rather than a set of rectangles.

The third is greatly improved tabbed node groups over base Hyprland, which is a specific criticism of the upstream implementation and a specific promise about this one. The fourth is optional autotiling, so the layout can be manual, automatic, or somewhere in between.

The audience is a Hyprland user who has used i3 or sway and wants that model with Hyprland's own rendering, animation and configuration. The readme says additional features may be suggested in the repository issues or in the project Matrix room, and there is a demo video linked from the header.

The project is a C++ plugin built with CMake, and the repository is small and conventional: a src/ directory, a CMakeLists.txt, a flake.nix with a flake.lock, a default.nix and a shell.nix for Nix users, a hyprpm.toml for the plugin manager, two scripts that generate compile command databases for bear and for cmake, a .clang-format, and an assets directory with the logo.

The author also maintains Quickshell, described as a toolkit for creating custom bars, widgets, lockscreens and other desktop shell components with first class support for Hyprland. That is worth knowing if you are building a Hyprland setup, because the two projects are maintained by the same person and will be maintained or not together.

One tag per Hyprland release, and what the lock file does

The stability section is the part of this project that a reader has to understand before installing anything, and it is unusually precise.

hy3 has a tagged release for each Hyprland update, and master tracks Hyprland's main branch. If you are running a release version of Hyprland then you use the matching tagged hy3 version, and if you are running an untagged Hyprland release then you use the master branch of hy3. The tags are formatted as hl followed by the version, where the version matches the Hyprland release version, so the recent ones are hl0.55.0, hl0.56.0 and hl0.56.0.1.

Then there is the build pinning, which is a different mechanism from the tags. Commits are tested before pushing and will build against the Hyprland release recorded in the flake.lock file. There may be a mismatch with Hyprland's main branch, and if hy3 fails to build against Hyprland's main branch the instruction is to open an issue or ping the author in the Matrix room. Tagged hy3 versions are always checked against the corresponding Hyprland tag.

So there are three states to be aware of. A tagged Hyprland with the matching tagged hy3 is the well tested combination. A tagged Hyprland with hy3 master is the bleeding edge combination, which builds against the pinned release in the lock file. And an untagged Hyprland build is the case where the plugin can fail to build or fail to load, and the installation notes repeat that attempting to use a mismatched Hyprland release will result in failure when building or loading hy3.

The bug report template is short and useful: the commit hash of the version you are running, the steps to reproduce the bug if you can figure them out, and a backtrace of the crash if applicable. The phrasing of the first two is a small sign of the audience, which is people running bleeding edge compositor builds and reporting problems from them.

Installing with Nix, and the home manager module

The Nix path is the most complete one, because the flake inputs encode the version matching rule for you.

If you use Hyprland's home manager module, integrating hy3 is adding it to the plugins array. The flake declares the two repositories with the version placeholder in the URL, so the same file works for a release or for the development branch:

    hyprland.url = "git+https://github.com/hyprwm/Hyprland?submodules=1&ref={version}";
    # where {version} is the hyprland release version
    # or "github:hyprwm/Hyprland?submodules=1" to follow the development branch

    hy3 = {
      url = "github:outfoxxed/hy3?ref=hl{version}"; # where {version} is the hyprland release version
      # or "github:outfoxxed/hy3" to follow the development branch.
      # (you may encounter issues if you dont do the same for hyprland)
      inputs.hyprland.follows = "hy3";
    };

The comment in the last line is the important instruction. The hy3 input follows the hyprland input, so the plugin is built against exactly the Hyprland revision you selected, and the parenthetical warns that you will hit problems if you do not do the same for both.

In the home manager configuration, the plugin is then added to the Hyprland plugin list:

        {
          wayland.windowManager.hyprland = {
            enable = true;
            plugins = [ hy3.packages.x86_64-linux.hy3 ];
          };
        }

There is also a manual Nix route for people who do not use home manager. The binary is available as a shared object at a path inside the package, and it is loaded through the Hyprland configuration:

  extraConfig = ''
    plugin = ${hy3.packages.x86_64-linux.hy3}/lib/libhy3.so
  '';

The Nix route is the one to prefer for a Hyprland user on Nix, because the version matching is expressed in the flake inputs rather than in a ritual of checking out the right tag.

hyprpm, and the case where it picks the wrong revision

Hyprland now has a dedicated plugin manager, and the documentation says it should be used when your package manager is not capable of locking hy3 builds to the correct Hyprland version.

The setup is a line in the Hyprland configuration, to be run once:

exec-once = hyprpm reload -n

And then the plugin is added by URL:

hyprpm add https://github.com/outfoxxed/hy3

Updates go through the same tool, and there is a force variant for the case where the Hyprland headers have not been updated:

hyprpm update

hyprpm update -f

The second of those is the interesting one, and the documentation explains the scenario: sometimes the headers from Hyprland are not updated, and a plugin built against stale headers will not work. The forced update is the escape from that.

The warning is the sharpest part of the whole installation section. When you are running a tagged Hyprland version, hyprpm at 0.34.0 or later will build against hy3's corresponding release. But if you are running an untagged build, the -git variant, hyprpm will build against hy3's latest commit, which means that if you are running an out of date untagged build of Hyprland, hyprpm may pick an incompatible revision of hy3. The stated fix is to update Hyprland or to manually build the correct version of hy3.

That is a real operational trap, because untagged Hyprland builds are common among people who track the compositor closely, and the failure arrives as a build or load error rather than as a clear message about version mismatch. It is also why the flake approach, where the inputs are pinned together, is safer for anyone who can use it.

Building from source, and the headers that must match

The manual build is the shortest path in the documentation, and it has one hard requirement.

You install Hyprland, including its headers and the pkg-config file, and then run two commands:

cmake -DCMAKE_BUILD_TYPE=Release -B build
cmake --build build

The plugin ends up at build/libhy3.so, and it is loaded the normal way, with the Hyprland wiki linked for the details of loading plugins.

The hard requirement is stated in bold in the readme: the Hyprland headers and the pkg-config file must be installed correctly, for the target version of Hyprland. That is the whole difficulty of the manual route. The build is a plugin that compiles against Hyprland's C++ headers, so the headers on the machine have to be the ones that match the running compositor, and a mismatch here produces a compile error or, worse, a plugin that builds and misbehaves.

The reason the pkg-config file is mentioned alongside the headers is that the build finds the headers and link settings through it, so a pkg-config file pointing at the wrong version is as bad as missing headers. On a distribution where Hyprland is packaged, that generally means installing the development package for the exact version you run, which is a package management detail that the Nix and hyprpm routes both handle for you.

The repository also ships the compile command database scripts, compile_commands_bear.sh and compile_commands_cmake.sh, which generate a compile_commands.json for editors and for tooling that expects one, a small convenience that shows the project is developed with an editor that wants it.

The Arch route, and the error it produces

The AUR instructions are marked deprecated, with a note that you should use hyprpm instead because it is simpler and less error prone. They are kept, though, and the reason is instructive.

The caution explains that pacman is not very reliable when it comes to building packages in the correct order. If you get a notification saying that hy3 was compiled for a different version of Hyprland, then your packages likely updated in the wrong order, or you have Hyprland headers in /usr/local. The fix is to remove the stray header and pkg-config locations, that is /usr/include/hyprland, /usr/local/include/hyprland, /usr/share/pkgconfig/hyprland.pc and /usr/local/share/pkgconfig/hyprland.pc, and then reinstall both Hyprland and hy3.

That error message is the most likely thing a new user will see, whichever installation route they pick, because it is the version mismatch expressing itself. The readme asks people who know how to fix it to open an issue or a pull request, or to message the author in the Matrix room, and there is a second Matrix room for support, so the two rooms have different purposes and the support one is where a user with a broken build belongs.

The general lesson from the AUR section is the same one the whole project keeps making. A Hyprland plugin is version coupled to the compositor, and the tooling exists to manage that coupling, and the failures happen at the boundaries where the coupling is not managed: a package manager that updates in the wrong order, headers left in a prefix that is not the one in use, a plugin manager pointed at an untagged build.

The project handles those cases as well as it can, and the documentation names each one, which is more than most plugin projects do.

Editorial conclusion

hy3 suits a Hyprland user who wants the keyboard driven, manual tiling of i3 and sway with Hyprland's own animation and configuration model, and it suits a Nix user because the home manager module and the flake inputs are already written. It is the wrong choice if you are on a Hyprland build that does not match a hy3 tag and you are not prepared to track the master branch, since a mismatched pair fails to build or to load. Before installing, check whether your Hyprland is a tagged release or an untagged one, because the installation method changes with that, and make sure the Hyprland headers and pkg-config file are installed for exactly that version.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. outfoxxed/hy3 on GitHub
4. README
5. Releases