# Where to Find Hyprland Themes and Plugins: A Complete Guide

> Discover where to find Hyprland themes and plugins. Learn how to enhance your desktop with custom looks and powerful extensions for the Hyprland window manager.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/hyprwm/Hyprland/blob/main/src/pointer/cursor/CursorManager.hpp)). Theme resolution follows this chain:

1. **Configuration Check**: Reads the `cursor` block in your [`hyprland.conf`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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:

```bash
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:

```ini
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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/hyprland.conf) using absolute paths:

```ini
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`](https://github.com/hyprwm/Hyprland/blob/main/src/plugins/PluginAPI.hpp) and export the required symbols. Here is a minimal implementation:

```cpp
// 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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/src/ipc/s1/Commands.cpp):

```bash
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`](https://github.com/hyprwm/Hyprland/blob/main/src/pointer/cursor/CursorManager.cpp)**: Contains `CCursorManager::changeTheme` for runtime cursor theme switching.
- **[`src/managers/XCursorManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/managers/XCursorManager.cpp)**: Implements `CXCursorManager::loadTheme` to parse `index.theme` files and resolve inheritance.
- **[`src/plugins/PluginAPI.hpp`](https://github.com/hyprwm/Hyprland/blob/main/src/plugins/PluginAPI.hpp)**: Defines the ABI, required symbols, and helper macros for plugin development.
- **[`src/plugins/PluginSystem.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/plugins/PluginSystem.cpp)**: Houses `CPluginSystem::updateConfigPlugins`, which orchestrates `dlopen`, symbol resolution, and plugin registration.
- **[`src/ipc/s1/Commands.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/CMakeLists.txt). The resulting `.so` file must expose C-linkage symbols (`extern "C"`) as defined in [`src/plugins/PluginAPI.hpp`](https://github.com/hyprwm/Hyprland/blob/main/src/plugins/PluginAPI.hpp) for the `CPluginSystem` to resolve them correctly.