Where to Find Hyprland Themes and Plugins: A Complete Guide

Hyprland themes are standard X-cursor themes managed by XCursorManager, while plugins are compiled shared-object libraries loaded dynamically via the CPluginSystem class.

This guide covers exactly where to locate cursor themes and plugin libraries for the Hyprland Wayland compositor, based on the official hyprwm/Hyprland source code. You will learn how the compositor resolves theme paths, loads external plugins at runtime, and which configuration files control these features.

Finding and Configuring Hyprland Themes

Hyprland does not store themes internally. Instead, it queries the standard X-cursor subsystem using the XCURSOR_THEME environment variable or the cursor:theme configuration option.

How Hyprland Resolves Cursor Themes

When Hyprland initializes, it instantiates CCursorManager (defined in src/pointer/cursor/CursorManager.hpp). Theme resolution follows this chain:

1. Configuration Check: Reads the cursor block in your hyprland.conf (e.g., theme = Nordzy).
2. Environment Fallback: If unspecified, checks the XCURSOR_THEME environment variable.
3. System Paths: Searches /usr/share/icons/, $HOME/.icons/, and directories listed in XCURSOR_PATH for the theme's index.theme file.

The actual parsing of theme metadata and inheritance chains occurs in src/managers/XCursorManager.cpp via the CXCursorManager::loadTheme method, which CCursorManager::changeTheme calls during initialization and theme switches.

Changing Themes at Runtime

Use the built-in IPC command to switch themes without restarting:

hyprctl cursor theme Breeze 32

This invokes CCursorManager::changeTheme, which reloads the cursor shapes via the XCursorManager backend.

Configuration Example

Add this to ~/.config/hypr/hyprland.conf to set a persistent theme:

cursor {
    theme = Nordzy
    size  = 24
}

Valid theme names correspond to directories containing cursors/ and index.theme files in your system's icon paths.

Finding and Installing Hyprland Plugins

Hyprland plugins are compiled .so files that extend the compositor using the Hyprland Plugin API. They are dynamically loaded by the CPluginSystem class at startup.

Official Plugin Sources

The hyprwm/Hyprland-Plugins repository hosts a curated collection of community-maintained plugins, including:

• hyprbars: Title bars for windows.
• hyprtricks: Additional window management utilities.
• hyprfocus: Focus animation enhancements.
• hyprsplit: Split-monitor workspace management.

Additional third-party plugins are listed in the Hyprland community wiki and Discord channels.

Loading Plugins via Configuration

The CPluginSystem::updateConfigPlugins method (implemented in src/plugins/PluginSystem.cpp) handles dynamic loading. When Hyprland parses its configuration, it:

1. Locates the file path specified in the plugin config entry.
2. Calls dlopen to load the shared object.
3. Resolves required symbols: pluginAPIVersion, pluginInit, and pluginExit.
4. Registers the plugin's IPC commands, callbacks, or decorations.

Specify plugin paths in hyprland.conf using absolute paths:

plugin = /home/user/.config/hypr/plugins/hyprbars.so
plugin = /home/user/.config/hypr/plugins/hyprtricks.so

Creating Custom Plugins

Plugins must include src/plugins/PluginAPI.hpp and export the required symbols. Here is a minimal implementation:

// myplugin.cpp
#include "plugins/PluginAPI.hpp"

extern "C" PLUGIN_DESCRIPTION_INFO pluginInit(void* hyprHandle) {
    HyprlandAPI::addConfigValue(hyprHandle, "plugin:myplugin:example", 42);
    return { "MyPlugin", "1.0", "Author", "https://github.com/your/me" };
}

extern "C" void pluginExit(void* hyprHandle) {
    // Cleanup resources if necessary
}

Compile with -fPIC and -shared flags (matching Hyprland's CMakeLists.txt settings) to produce a loadable .so file.

Inspecting Loaded Plugins

Verify active plugins using the IPC interface defined in src/ipc/s1/Commands.cpp:

hyprctl plugins

This outputs a list of currently loaded shared objects managed by the plugin system.

Key Implementation Files

Understanding these source files helps debug theme and plugin issues:

• src/pointer/cursor/CursorManager.cpp: Contains CCursorManager::changeTheme for runtime cursor theme switching.
• src/managers/XCursorManager.cpp: Implements CXCursorManager::loadTheme to parse index.theme files and resolve inheritance.
• src/plugins/PluginAPI.hpp: Defines the ABI, required symbols, and helper macros for plugin development.
• src/plugins/PluginSystem.cpp: Houses CPluginSystem::updateConfigPlugins, which orchestrates dlopen, symbol resolution, and plugin registration.
• src/ipc/s1/Commands.cpp: Implements the hyprctl cursor theme and hyprctl plugins commands.

Summary

• Themes are standard X-cursor themes installed system-wide; Hyprland references them via cursor:theme or XCURSOR_THEME, resolved through XCursorManager.
• Plugins are compiled .so files loaded from absolute paths specified in the configuration; the CPluginSystem class handles dynamic linking via src/plugins/PluginSystem.cpp.
• Official plugins reside in the hyprwm/Hyprland-Plugins repository.
• Runtime inspection is available through hyprctl cursor theme and hyprctl plugins.

Frequently Asked Questions

Where does Hyprland look for cursor themes?

Hyprland searches standard Linux icon directories: /usr/share/icons/, $HOME/.icons/, and any path referenced by the XCURSOR_THEME environment variable. The CXCursorManager class in src/managers/XCursorManager.cpp parses the theme's index.theme file to resolve the actual cursor assets.

Can I use plugins from unofficial sources?

Yes. Any compiled shared object that exports the required pluginAPIVersion, pluginInit, and pluginExit symbols can be loaded. Place the .so file in a directory like ~/.config/hypr/plugins/ and reference it with an absolute path in your configuration. However, unofficial plugins may compromise stability if they misuse the Plugin API.

How do I reload plugins without restarting Hyprland?

While Hyprland supports changing cursor themes at runtime via hyprctl, reloading plugins dynamically is not recommended and may not be fully supported. The CPluginSystem::updateConfigPlugins method primarily processes plugins during the initial configuration load. For updates, you typically need to restart the compositor to ensure clean initialization of the new shared objects.

What compiler flags are required to build a Hyprland plugin?

Plugins must be compiled as position-independent code using -fPIC and linked as shared libraries with -shared, matching the flags used in Hyprland's CMakeLists.txt. The resulting .so file must expose C-linkage symbols (extern "C") as defined in src/plugins/PluginAPI.hpp for the CPluginSystem to resolve them correctly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}