hyprshell 4.11.0-alpha.1

A modern GTK4-based window switcher and application launcher for Hyprland
hyprshell-4.11.0-alpha.1 is not a library.

Hyprshell

crates.io Docs Tests

img.png

Overview

Hyprshell (previously hyprswitch) is a modern GTK4-based window switcher and application launcher for Hyprland. It provides a customizable GUI for switching between windows or workspaces, launching applications, and running launcher actions from the keyboard.

Features

  • Window Switching: Switch between windows or workspaces using keyboard shortcuts in a GUI.
  • Customizable Keybindings: Define your own keybindings for window switching and GUI interactions.
  • Settings App: Customize switching, launcher behavior, keybindings, and themes using a settings app.
  • Launcher Integration: Launch applications directly from the GUI, sorted by usage frequency.
  • Launcher Plugins: Different plugins like Web search, terminal commands, actions, or calculations can be enabled.
  • Theming: Customize the GUI appearance (gtk4) using CSS, Settings app comes with some default themes.
  • Dynamic Configuration: Automatically reloads configuration/style changes without restarting the application.
  • Debug commands: Many Commands to debug desktop files, icons, launcher matching, and default applications.
  • Nix Support: Includes a flake and home-manager module for Nix-based setups.
  • Live Window Preview (Experimental): Can use live window content directly within the overview.

Installation

Minimum Hyprland version: 0.55.0, using lua or legacy configuration

Packaging status

Arch Linux (AUR)

paru -S hyprshell
# or
yay -S hyprshell

Use hyprshell-bin for the pre-built binaries from GitHub releases.

Use hyprshell-slim for the slim version (faster buildtime).

Binary pre-built packages (only for x86_64 and aarch64)

Download and extract from the latest release on the releases page.

Look at bin-pkbuild to see which files need to be installed where. DON'T just copy only the executable, else the settings app won't work correctly.

NixOS

Hyprshell is also available in nixpkgs repository and can be configured using a generic home-manager module.

This repository also contains a flake and a type-safe home-manager module for configuration.

Please read NixOS if you use flakes.

From Source

hyprland, gtk4[v4_18], libadwaita[v1_8] and gtk4-layer-shell[1.1.1] must be installed

cargo install hyprshell

Build with fewer features in slim mode

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

Minimum required rustc version: 1.92.0 (from 11 December 2025)

Look at pkbuild to see which files need to be installed where. DON'T just build only the executable, else the settings app won't work correctly.

Usage

Run hyprshell --help to see available commands and options.

Config

To generate or edit a configuration, run hyprshell config generate, hyprshell config edit or launch the Hyprshell Settings Editor App. (they all do the same thing)

To validate or explain the current configuration, use hyprshell config check and hyprshell config explain.

Initialization

Enable the systemd service [recommended]:

systemctl --user enable --now hyprshell.service

This will only work if you either use uwsm or have Systemd Startup configured. Check with systemctl status graphical.target to see if hyprshell would be started.

Or add the following to your Hyprland configuration (~/.config/hypr/hyprland.conf):

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

image.png img.png

Debugging

Debug commands are provided to help troubleshoot desktop files, icons, launcher search results, default applications, and general system information, see Debug.md for detailed information about available commands and their usage.

Feature Flags

✅ = included in the default feature set.

✨ = included in the slim feature set. (build with --no-default-features --features "slim")

  • json5_config✅: Adds support for a json5 config file.
  • gui_settings_editor✅✨: Adds the hyprshell config edit + hyprshell config generate command to open the settings editor.
  • launcher_calc✅: Adds support for the calc plugin in the launcher.
  • live_windows✅: Adds support for live window preview in the overview and switch windows.
  • ci_config_check: (!used for ci tests) Adds a command to check if the loaded config is equal to the default config or the full config.
  • dev: Used to deactivate migrations and other checks. Used if config changes are not implemented in the migrations.

Env Variables

You can override these via systemctl --user edit hyprshell.service by setting Environment="HYPRSHELL_...=value" in a [Service] block

  • HYPRSHELL_NO_LISTENERS: Disable all config listeners (config file, css file, hyprland config, monitor count)
  • HYPRSHELL_NO_ALL_ICONS: Don't check for all icons on fs and just use the ones provided by the gtk4 icon theme.
  • HYPRSHELL_RELOAD_DELAY: Set the delay for starting the restart listeners(config, css, monitors, hypr-config) in milliseconds (default: 1000).
  • HYPRSHELL_RELOAD_DEBOUNCE: Set the debounce time in milliseconds for reloading hyprshell after a message from restart listeners (default: 750).
  • HYPRSHELL_LOG_MODULE_PATH: Add the module path to each log message. (use with -vv)
  • HYPRSHELL_EXPERIMENTAL: Enables experimental features (grep through the source code for "HYPRSHELL_EXPERIMENTAL" to see them)
  • HYPRSHELL_RUN_ACTIONS_IN_DEBUG: Run actions from launcher plugin in debug mode