A Hyprland plugin manager

Important

Plugin Developers: hyprload has recently been refactored to no longer provide HYPRLAND_HEADERS. As far as I know, this wasn't used anywhere, but if you encounter issues (missing headers, etc.) that's a sign for you to move to pkg-config. hyprload now always provides a known good version of headers via pkg-config by overriding it.

Warning

Users As part of the above changes, you might want to reinstall hyprload, as the place where Hyprland headers were stored has changed. You could now be keeping a useless, pretty big duplicate repository in ~/.local/share/hyprload/hyprland (moved to ~/.local/share/hyprload/include/hyprland). To reinstall, simply rm -rf ~/.local/share/hyprload and proceed to Installing

Features

Requirements

Hyprland >= 0.31.0
jq (required for checking Hyprland version)
polkit (required to set up Hyprland plugin env)
- You will need an authentication agent set up. lxsession works for me.
cpio (required during installation for file management)

Installing

Install hyprload
- curl -sSL https://raw.githubusercontent.com/Duckonaut/hyprload/main/install.sh | bash
Add this to your config to initialize hyprload
- exec-once=$HOME/.local/share/hyprload/hyprload.sh

Setup

To have hyprload manage your plugin installation, create a hyprload.toml file (by default, next to your hyprland.conf config: ~/.config/hypr/hyprload.toml
Fill it out with the plugins you want. It consists of one array, named plugins, in which you can provide the installation source in various ways. Example:

plugins = [
    # Installs the plugin from https://github.com/Duckonaut/split-monitor-workspaces
    "Duckonaut/split-monitor-workspaces",
    # A more explicit definition of the git install
    { git = "https://github.com/Duckonaut/split-monitor-workspaces", branch = "main", name = "split-monitor-workspaces" },
    # Installs the same plugin from a local folder
    { local = "/home/duckonaut/repos/split-monitor-workspaces" },
]

Add keybinds to the hyprload dispatcher in your hyprland.conf for the functions you want.
- Possible values:
  - load: Loads all the plugins
  - clear: Unloads all the plugins
  - reload: Unloads then reloads all the plugins
  - install: Installs the required plugins from hyprload.toml
  - update: Updates hyprload and the required plugins from hyprload.toml
- Example:

bind=SUPERSHIFT,R,hyprload,reload
bind=SUPERSHIFT,U,hyprload,update

Configuration

The configuration of hyprload behavior is done in hyprland.conf, like a normal plugin

Name	Type	Default	Description
`plugin:hyprload:quiet`	bool	false	Whether to hide the notifications
`plugin:hyprload:debug`	bool	false	Whether to hide extra-special debug notifications
`plugin:hyprload:config`	string	`~/.config/hypr/hyprload.toml`	The path to your plugin requirements file
`plugin:hyprload:hyprland_headers`	string	`empty`	The path to the Hyprland source to force using as headers.

Plugin Development

If you maintain a plugin for Hyprland, to support automatic management via hyprload.toml, you need to create a hyprload.toml manifest in the root of your repository. hyprload cannot assume the way your plugins are built.

Format

The plugin manifest needs to specify some information about the plugins in the repo. If you're familiar with TOML, it means specifying two dictionaries per plugin - PLUGIN_NAME and PLUGIN_NAME.build. The PLUGIN_NAME dictionary has basic information about the plugin like the version, the description and the author. These are not used currently, and can be omitted if you don't want to bother for now.

The PLUGIN_NAME.build dictionary is much more important, as it holds 2 important values: output, which is the path to the built plugin .so from the repo root, and steps, which holds the commands to run to build that .so. hyprload will define HYPRLAND_HEADERS while building the plugin, and guarantees the version of the headers matches the Hyprland version you're running.

It's important to note that the hyprload.toml plugin manifest can hold multiple plugins. This allows you to define a single manifest for a monorepo.

The full specification of a PLUGIN_NAME dict:

Name	Type	Description
description	string	Short description
version	string	Version
author	string	Author
authors	list	Can be defined instead of `author`
build.output	string	The path of the `.so` output
build.steps	list	List of commands to build the `.so`

Examples

Single plugin

split-monitor-workspaces

[split-monitor-workspaces]
description = "Split monitor workspaces"
version = "1.0.0"
author = "Duckonaut"

[split-monitor-workspaces.build]
output = "split-monitor-workspaces.so"
steps = [
    "make all",
]

Multiple plugins

Here's what the manifest would look like for the official plugins.

[borders-plus-plus]
description ="A plugin to add more borders to windows."
version = "1.0"
author = "Vaxry"

[borders-plus-plus.build]
output = "borders-plus-plus/borders-plus-plus.so"
steps = [
    "make -C borders-plus-plus all",
]

[csgo-vulkan-fix]
description = "A plugin to fix incorrect mouse offsets on csgo in Vulkan"
version = "1.0"
author = "Vaxry"

[csgo-vulkan-fix.build]
output = "csgo-vulkan-fix/csgo-vulkan-fix.so"
steps = [
    "make -C csgo-vulkan-fix all",
]

[hyprbars]
description = "A plugin to add title bars to windows"
version = "1.0"
author = "Vaxry"

[hyprbars.build]
output = "hyprbars/hyprbars.so"
steps = [
    "make -C hyprbars all",
]

Duckonaut/hyprload

Duckonaut

Reviews

Repository Details