Hyprland

What it is

Hyprland is a Wayland compositor, the program that draws and arranges the windows on your screen. It tiles them for you, and also does floating, fullscreen and pseudotiled windows, scratchpad workspaces and tabbed window groups. The README calls it 100% independent, with no wlroots, libweston, kwin or mutter underneath. It is not a desktop environment. The Installation page calls it a set of tools to build your own, so apps, integrations and shells are yours to pick, install and configure.

1. You install Hyprland from your distribution’s packages
2. You run start-hyprland from a TTY
3. It writes an example hyprland.lua if none exists
4. You change binds, monitors and looks in Lua
5. It reloads the config each time you save

Who it suits

Linux users who drive their desktop from the keyboard and are happy to assemble the rest themselves. The Installation page calls its own wiki very verbose and asks you to read it before assuming something is broken. If you want a finished desktop on the first boot, start from one of the preconfigured setups the wiki lists, or skip it.

Where to use it

Hyprland runs on Linux, and the Installation page lists FreeBSD packages as well. The team officially runs and tests it on Arch and NixOS. Every other line on that page is a community package with no guarantee.

• Arch: the tagged release from the official repositories, or the -git packages from the AUR
• NixOS: one line in configuration.nix, or the Hyprland flake for the latest commit
• openSUSE, Fedora, Debian, Gentoo, Ubuntu, Alpine, Void, Ximper, Solus and FreeBSD: the community packages
• The page warns that point-release distributions such as Pop!_OS, Fedora and Ubuntu will have major issues running Hyprland. It says Ubuntu 26.04 and earlier ship an extremely outdated package it does not recommend at all, and that on Ubuntu only 26.10’s apt package is recommended
• Any systemd distribution: the Nix package manager, which the wiki suggests where support is poor
• A virtual machine: with 3D acceleration turned on, which the wiki says is not officially supported

How to set it up

Get it saves a zip of Minda’s setup notes in your downloads folder, with a page for each route above and pages for the first launch, plugins and fixes. The install itself is one package.

1. Install it with your package manager. The wiki heavily recommends the distribution’s package over a source build or -git packages.
2. Install kitty, the default terminal.
3. On NVIDIA, follow the NVIDIA page. The Installation page says these cards are often not usable out of the box.
4. Run start-hyprland from a TTY. The Master tutorial says never with root permissions.
5. Press SUPER + Q to open kitty.

On Arch, the Installation page gives:

sudo pacman -S hyprland

On NixOS, the Hyprland on NixOS page puts this in configuration.nix:

{
  programs.hyprland.enable = true;
}

Then, from a TTY:

start-hyprland

How to use it

The example config sets SUPER, the Windows key, as the main modifier. These keys come from its KEYBINDINGS section.

• SUPER + Q opens kitty, and SUPER + C closes the active window
• SUPER + R opens the hyprlauncher menu, and SUPER + E the dolphin file manager
• SUPER + 1 to 0 switch workspaces, and SUPER + SHIFT + a number moves the window there
• SUPER + V switches a window between floating and tiled, and SUPER + S shows or hides the scratchpad workspace
• SUPER + M exits Hyprland

hyprctl ships with Hyprland and talks to the running session. These list your windows and every monitor, and force a reload:

hyprctl clients
hyprctl monitors all
hyprctl reload

Example

You want SUPER + SHIFT + Q to open Firefox. Open ~/.config/hypr/hyprland.lua and add the line the Binds page gives:

-- bind SUPER + SHIFT + Q to open Firefox
hl.bind("SUPER + SHIFT + Q", hl.dsp.exec_cmd("firefox"))

Save the file and Hyprland reloads the config on its own. SUPER + SHIFT + Q now opens Firefox. A typo pops an error on screen, and hyprctl configerrors lists the current ones.

For newcomers and experts

If you are new. Plasma and GNOME start a set of helpers for you. Hyprland does not. The Must-have page lists what to add: a notification daemon such as dunst or mako, PipeWire for screen sharing, an XDG desktop portal, an authentication agent, Qt Wayland support and fonts. Without a notification daemon, many apps may freeze. Keep the example config and change one thing at a time.

The Preconfigured setups page lists dotfiles, such as Omarchy and ML4W, for a DE-like start, and the Master tutorial says these dotfiles should do everything for you. The Preconfigured setups page also warns that many of them change your system at a deep level and can be hard to remove.

For experts. The config is Lua, and require loads other files. The Core page says each require runs as its own scope, so an error in one file does not stop the rest. A Lua stub in /usr/share/hypr/stubs gives your editor autocompletion. hyprctl eval runs Lua in the live session, and hyprctl repl opens a REPL:

hyprctl repl 'hl.get_active_window().class'

Building from source needs a C++26 compiler (gcc 16 or newer, or clang 19 or newer) and every hypr* library, built in the order the Installation page gives. The FAQ says you cannot mix packaged and self-built hypr* parts. CMake flags can remove Xwayland support or the systemd dependencies, or skip the UWSM session file or hyprpm.

Good to know

The wiki follows the latest git commit by default, and you probably run a tagged release. Check yours with hyprctl version and pick it in the wiki’s version selector.

• Building yourself: the Installation page puts .so mismatch errors on you, and the FAQ says never to symlink different .so versions
• Code you load: a Lua config can run arbitrary code, and plugins are C++ that runs inside Hyprland. Read both before you use them
• Packages: the Hypr* team maintains none of them, and the page says to try a source build if one is broken
• Usage data: the README and the wiki pages Minda read say nothing about telemetry
• Removal: those pages give no uninstall steps. Remove the package the way you installed it, and keep ~/.config/hypr if you want your config
• License: BSD 3-Clause, “Copyright (c) 2022-2026, vaxerski”
• Not an endorsement: these notes are Minda’s, and the Hyprland project did not write or review them