Hyprshell puts a GTK4 window switcher on top of Hyprland

A window switcher for one compositor

Hyprshell, previously known as hyprswitch, is a modern GTK4-based window switcher and application launcher for Hyprland. The scope is narrow in a way that should be the first thing you evaluate. This is a tool for a specific Wayland compositor, and the repository topics are hyprland and wayland and nothing else. It provides a customizable GUI for switching between windows or workspaces, launching applications and running launcher actions from the keyboard. The GUI is GTK4 with libadwaita, and the code is Rust, with the workspace package description reading the same way. What that buys a Hyprland user is a graphical switcher with a window list, an application launcher sorted by usage frequency, and a settings app for adjusting switching behaviour, launcher behaviour, keybindings and themes. What it does not buy is portability, and the dependency list makes the reason concrete: the build requires Hyprland itself alongside gtk4 version 4_18 or newer, libadwaita version 1_8 or newer and gtk4-layer-shell, which is the library that lets a GTK application draw itself as a desktop layer surface rather than a normal window.

The Hyprland version floor and the lua configuration

There is a hard compatibility statement near the top of the installation section: minimum Hyprland version 0.55.0, using lua for configuration. That is worth pausing on, because the lua configuration requirement means your Hyprland setup has to be in the newer configuration style for Hyprshell's integration to be meaningful. The project assumes a current compositor, and the floor is a genuine constraint rather than a soft recommendation. The application itself also demands a recent toolchain. The minimum required rustc version is 1.92.0, dated 11 December 2025 in the README, and the workspace manifest agrees, setting rust-version to 1.92.0 and edition to 2024. The README points at a packaging status badge for distribution coverage, so the number of repositories carrying the package is visible before you install. If your compositor predates 0.55.0 or you are not using lua, this is a case where the answer is simply not yet, and the packaging badge will tell you whether anyone in your distribution is shipping a version at all.

Installing: AUR, prebuilt binaries, nixpkgs or cargo

Four install routes are documented. On Arch Linux the AUR packages are the usual route.

paru -S hyprshell
# or
yay -S hyprshell

There are AUR variants for the pre-built binaries from the GitHub releases, hyprshell-bin, and for the slim build, hyprshell-slim, which trades features for a faster build time. The pre-built release archives themselves are only for x86_64 and aarch64, so if you are on another architecture the binary route is closed to you. For Nix users, Hyprshell is in the nixpkgs repository and can be configured with a generic home-manager module, and the repository itself carries a flake and a type-safe home-manager module, with separate NixOS documentation for flake users. Building from source is a single cargo install, provided the GTK4 stack is already present.

cargo install hyprshell

And there is a reduced build for people who want the fast compile time rather than the full feature set.

cargo install hyprshell --no-default-features --features "slim"

Bringing the daemon up: systemd service or Hyprland hook

The daemon has to be running for the switcher to respond, and there are two documented ways to start it. The recommended one enables a systemd user service, with the service file generated by the config generator.

systemctl --user enable --now hyprshell.service

The alternative is a hook in your Hyprland configuration file, ~/.config/hypr/hyprland.conf, written in the lua configuration style.

hl.on("hyprland.start", function()
    -- Run hyprshell daemon
    hl.exec_cmd("hyprshell run")
end)

The distinction matters for anyone who logs in through a display manager rather than a TTY, since the two mechanisms start the daemon at different points in the session lifecycle. The Hyprland hook ties the daemon's lifetime to the compositor's own start event, while the systemd user unit ties it to the user session. Picking the wrong one is a common source of a switcher that never appears, and the two are not exclusive, so it is worth being deliberate about which one you configure rather than adding both.

Configuration as a file you can generate, edit and explain

The configuration story is more CLI-heavy than a typical GTK application, and that is where the project's personality shows. You can generate a configuration, edit one, or launch the Hyprshell Settings Editor app, and the same tool validates and explains the configuration currently in effect.

The four subcommands are `hyprshell config generate`, `hyprshell config edit`, `hyprshell config check` and `hyprshell config explain`.

Beyond the config subcommand, the CLI tool surface covers validating configs, changing default applications, inspecting launch history and generating shell completions. The config check and config explain pair is the part that earns its keep in practice. Check tells you whether what is on disk is what the daemon loaded, and explain describes the configuration as the running process sees it, which is the difference between a file you edited and a file that took effect. There is also a ci_config_check feature flag, described as used for CI tests, which adds a command to check whether the loaded config equals the default config or the full config, and which also disables loading of configs that do not have all values. The debug commands are separately documented for troubleshooting desktop files, icons, launcher search results, default applications and general system information.

Feature flags: what the slim build actually drops

The feature flag list is the most useful description of the project's architecture, because it shows which pieces are independent. The gui_settings_editor flag adds the hyprshell config edit command that opens the settings editor. json5_config adds support for a json5 config file, which is a second configuration format alongside the default. launcher_calc adds the calc plugin in the launcher. debug_command adds the hyprshell debug command. The clipboard flags are where the list gets long, and they are the most interesting group: clipboard_compress_lz4, clipboard_compress_brotli and clipboard_compress_zstd each add a compression method for clipboard content, while clipboard_encrypt_chacha20poly1305 and clipboard_encrypt_aes_gcm add encryption. The pattern is a set of orthogonal capabilities selected at compile time, which is why a slim build exists at all. A user who never touches the clipboard can compile out the compression and encryption code entirely, and the tradeoff is a build that is faster to produce at the cost of losing features you might later want, since switching later means another compile.

Launcher plugins and a usage-sorted application list

The launcher does more than start programs. It can launch applications directly from the GUI, sorted by usage frequency, which is a small idea with a large effect on how quickly you reach the thing you actually use. On top of that sit launcher plugins, described as different plugins like web search, terminal commands, actions or calculations, any of which can be enabled, and the calc plugin in particular is called out with its own feature flag. The settings app covers switching, launcher behaviour, keybindings and themes, so most of the day to day adjustment happens in a GUI rather than in a config file, which is the opposite of the CLI-heavy config workflow described earlier and suggests the project is serving two preferences at once. Theming works through CSS, documented in docs/CONFIGURE.md, with the settings app shipping some default themes. And the application reloads configuration and style changes automatically without a restart, so the CSS and config loop is a save and watch workflow rather than a restart loop.

Environment variables for the awkward cases

The env var list is where the project documents its own sharp edges, and it is worth reading before you debug a problem. HYPRSHELL_NO_LISTENERS disables all config listeners, covering the config file, the CSS file, the Hyprland config and the monitor count, which is the switch to flip when the automatic reload behaviour is causing trouble. HYPRSHELL_NO_ALL_ICONS tells the tool not to check the filesystem for all icons and to use only the ones provided by the gtk4 icon theme, which speeds up startup and works around a missing or slow icon directory. HYPRSHELL_RELOAD_DELAY sets the delay before starting the restart listeners in milliseconds, defaulting to 1000, and HYPRSHELL_RELOAD_DEBOUNCE sets the debounce time for reloading after a listener message, defaulting to 2000. The last two exist because a config change can produce several listener events, and without a debounce you would restart the shell several times for one edit. HYPRSHELL_LOG_MODULE_PATH adds the module path to each log message for use with the verbose flag, HYPRSHELL_EXPERIMENTAL enables experimental features, and HYPRSHELL_RUN_ACTIONS_IN_DEBUG runs launcher plugin actions in debug mode.

Editorial conclusion

Adopt Hyprshell if you run Hyprland and want a graphical window switcher, a usage-sorted launcher and a settings app instead of keyboard-only workflows, and if you are comfortable with a compositor-specific tool. Do not adopt it if you use another Wayland compositor, if you cannot meet the minimum of Hyprland 0.55.0 configured with lua, or if you want a lean build, in which case the slim feature set is the version to look at. Verify two things first: that the pre-built binary matches your architecture, since the release archives are only published for x86_64 and aarch64, and that the daemon starts the way you intend, because the systemd user service and the Hyprland configuration hook are two different ways to bring it up. The practical first step is to run hyprshell config generate, then hyprshell config check to see whether the generated configuration is what the running daemon actually loaded.

Frequently asked questions

Official sources

1. H3rmt/hyprshell on GitHub
2. License: MIT
3. Project website
4. README
5. Releases