Hyprspace: a KDE-style workspace overview for Hyprland

The overview panel that other desktops ship by default

Hyprspace is a plugin for Hyprland that implements a workspace overview feature similar to that of KDE Plasma, GNOME and macOS, aimed at providing an efficient way of workspace and window management.

The gap it fills is specific. Hyprland is a tiling window manager with a fast, keyboard-driven workflow, and it does not include the spatial overview that GNOME, KDE and macOS users take for granted. In those desktops you can open an overview, see every window on every workspace at once, and drag a window from one workspace to another. Hyprspace adds that surface to Hyprland.

The feature list in the README is more specific than the headline. There is a workspace minimap and a workspace display, mouse controls that include moving a window between workspaces and creating new workspaces, animation support, multi-monitor support, monitor scaling support, aarch64 support with no function hook used, and touchpad and gesture support including a workspace swipe, scrolling through the workspace panel and a swipe to open.

The behaviour settings are the part that determines whether the panel feels native. Autodrag windows, autoscroll workspaces, responsive workspace switching, and responsive exiting, which covers both exiting on click or switch and exiting with the escape key, are all implemented. There is also workspace blacklisting, with separate switches for showing or hiding new and empty workspaces and for showing or hiding the special workspace, which the README identifies as number 11.

The audience is Hyprland users who want the overview, and the README's own video link shows the panel with a drag in progress.

It is a shared object that hyprctl loads at runtime

The mechanism is Hyprland's plugin interface, and the README's manual instructions describe it exactly.

To build, you need the hyprland headers installed, and under the repository directory you run make all. Then you use hyprctl plugin load followed by the absolute path to the .so file to load it, and you could add this to your exec-once to load the plugin on startup.

So the artefact is a shared library, not an executable, and the load happens through the compositor's own control command at runtime. That is why the path has to be absolute, and why the exec-once line matters: a plugin that is not loaded is simply not there, with no error until you look for a feature that is missing.

The Makefile shows the shape of the code. The target is Hyprspace.so, built from every source file under src with a wildcard, and the compile flags are the interesting part: -shared and -fPIC to produce a shared object, --no-gnu-unique because that symbol breaks the symbol interposition model that plugins rely on, -std=c++2b for the C++23 support a modern compositor API needs, and -DWLR_USE_UNSTABLE because the plugin uses unstable wlroots interfaces. The include list is pulled from pkg-config for pixman-1, libdrm, hyprland, pangocairo, libinput, libudev, wayland-server, xkbcommon and lua, which tells you that this plugin draws with cairo, talks to input devices, and links the Lua runtime.

The install target copies the built object into the library directory with install -D and mode 0755, and there is a withhyprpmheaders variant that points pkg-config at the headers Hyprpm keeps in its own data directory, so the plugin can be built against the exact Hyprland headers the plugin manager installed.

Opening it, and what the mouse does once it is open

The interaction model is short enough to read in one sitting.

You bind the overview:toggle dispatcher, or perform a workspace swipe vertically, and the panel opens or closes. Inside it, clicking a workspace switches to it, clicking a window picks it up so you can drag it, and dragging a window into a workspace moves the window there. To leave, you click without dragging a window, which exits the overview, or press ESC.

When there are many workspaces open, you scroll or swipe on the panel to pan through them, which pairs with the autoscroll behaviour in the roadmap.

The dispatchers are the configuration surface, and there are three. overview:toggle toggles the workspace overview on the current monitor, overview:close closes the overview on the current monitor if opened, and overview:open opens it on the current monitor if closed. Adding the all argument to these dispatchers would toggle, open or close the overview on all monitors, which is the only multi-monitor handling exposed at the configuration level.

The panel is also reachable by gesture rather than only by key, and the roadmap lists a workspace swipe, scrolling through the workspace panel and a swipe to open under touchpad and gesture support, so the plugin is built for a trackpad user rather than only for a mouse user.

Configuration moved into Lua, and the old keys still exist

The configuration story has two layers, and the older one is the first thing a long time user of this plugin will look for.

The styling keys are named plugin:overview: followed by the setting. There is panelColor, panelBorderColor, workspaceActiveBackground, workspaceInactiveBackground, workspaceActiveBorder and workspaceInactiveBorder, plus dragAlpha, which overrides the alpha of the window when dragged in overview, on a scale from 0 to 1 where 0 is transparent and 1 is opaque, and disableBlur. The layout keys are panelHeight, panelBorderWidth and onBottom.

The newer layer is Lua. Starting with Hyprland 0.55+, the configuration format has transitioned to Lua as the default, at ~/.config/hypr/hyprland.lua, and the plugin's settings are structured nested within the hl.config() table under plugin.overview:

hl.config({
    plugin = {
        overview = {
            panelColor = "#1e1e2e",
            panelBorderColor = "#cba6f7",
            workspaceActiveBackground = "rgba(49, 50, 68, 0.8)",
            workspaceActiveBorder = "rgb(203, 166, 247)",
            onBottom = false,
            autoDrag = true,
            -- Add other overview settings here
        }
    }
})

For dispatchers in Lua, Hyprspace registers wrapper functions in the hl.plugin.overview namespace, and they can be bound in your configuration, run inside callbacks, or executed from the command line. The three functions are hl.plugin.overview.toggle(arg), open(arg) and close(arg).

One detail in the binding example is easy to miss. When binding the Lua wrapper functions with hl.bind, you must wrap the call in a function definition, and passing the all argument toggles the overview on all monitors.

So a configuration migration is a two step job: the settings move into the Lua table, and the keybindings move into hl.bind wrappers. Neither is automatic.

The compatibility list, and the plugins that are out of scope

The README has a Plugin Compatibility section, and it is short and specific in a way that saves a debugging session.

hyprsplit is listed as tested with explicit support, and so is split-monitor-workspaces. hyprexpo is tested but comes with the note of minor bugs. And then there is the catch-all: any layout plugin is supported except ones that override Hyprland's workspace management.

That exception is the important one, and it follows from what the overview is. The panel draws Hyprland's workspaces and moves windows between them, so it depends on the workspace model being the one it expects. A plugin that rewrites how workspaces are managed changes the thing Hyprspace is a view of, and the two will disagree.

The hyprexpo entry is the only one that comes with a caveat.

For a user on a busy Hyprland setup, the practical check before installing is to read that list against the plugins already loaded, and to test the overview alongside them rather than in isolation. The README marks multi-monitor support and monitor scaling support as tested, and aarch64 support as using no function hook, which is a specific and reassuring detail for ARM users.

The maintainer points you at niri, and that is the real alternative

The README's most useful paragraph is the note at the top, and it is worth quoting because it changes how you should read the project.

The plugin is still maintained, by the combined efforts of the author and all the awesome contributors. However, the author says he does not have as much time to spend on it as before, and Hyprland is a rapidly changing codebase. Therefore, at this time, he could not guarantee that new issues could be resolved promptly.

That is a direct statement about the support you can expect, from the person who would fix it. It is more useful than a version number.

And then the recommendation, which is a genuine alternative rather than a rhetorical gesture. The author suggests giving niri a try for anyone considering an alternative to Hyprland. It is a scrolling window manager that offers a great built-in overview feature that allows dragging windows in-between workspaces just like this plugin does. It also has better workspace management as it cleans up empty workspaces like GNOME does.

The difference in approach is precise. Hyprspace is a plugin that bolts an overview onto a compositor whose model was not designed around one, and it has to track Hyprland's internals to do it, which is exactly why a rapidly changing upstream codebase is a problem. niri is a window manager whose layout model is scrolling, so the overview is a view of its own native structure, and it cleans up empty workspaces the way GNOME does.

The trade is the price of that coherence: you change window manager, and with it your keybindings, your layout habits and your rules.

Two install paths, a plugin manager, and a GPL-2.0 licence

There are three documented ways to get the plugin, and the Hyprpm route is the shortest.

The manual route is the build and load described earlier: make all in the repository, then hyprctl plugin load with the absolute path. The Hyprpm route installs from the repository URL and enables the plugin:

hyprpm add https://github.com/KZDKM/Hyprspace
hyprpm enable Hyprspace

The Nix route is a flake, and the README points at the Hyprland wiki for plugins. The important detail in the example flake is the follows relationship: Hyprspace uses latest Hyprland, and this is declared to keep them in sync, with inputs.hyprland.follows = "hyprland". The plugin is then added to wayland.windowManager.hyprland.plugins as inputs.Hyprspace.packages.${pkgs.system}.Hyprspace.

The licence is GPL-2.0, with the LICENSE file at the root of the repository, and the repository carries a hyprpm.toml for the plugin manager, a meson.build alongside the Makefile, and a flake.nix and flake.lock for the Nix route.

One last observation from the roadmap, because it is the most honest part of the documentation. The overview interface is done, mouse controls are partly done, with moving a window between workspaces and creating new workspaces finished but dragging windows between workspace views not, and configurability is partly done, with vertical layout on the left or right and unique styling for special workspaces still open. The maintainer's note about limited time and the unchecked boxes are consistent with each other, and a user deciding on this plugin should read both.

Editorial conclusion

Hyprspace fits a Hyprland user who has come from a desktop with a built-in overview and misses dragging a window onto another workspace. It does not fit someone who needs the feature to be finished, since the roadmap still lists dragging windows between workspace views and vertical layout as unfinished, and the maintainer warns that Hyprland is a rapidly changing codebase. Before you build it, read the compatibility list, because any layout plugin that overrides Hyprland's workspace management is out of scope, and check the Lua configuration section if you are on Hyprland 0.55 or newer, because the plugin settings moved into hl.config().

Frequently asked questions

Official sources

1. Issues
2. KZDKM/Hyprspace on GitHub
3. License: GPL-2.0
4. README