Installation

Warning

Hyprland is not meant to be a full and user-friendly Desktop Environment. In a nutshell, it’s a set of tools to allow you to create your own Desktop Environment.

Apps, integrations, shells, etc, are your responsibility to pick, install and configure.

This wiki is very verbose. It’s highly recommended to scour and read the wiki first before assuming something is not working or not available.

Note

NVIDIA GPUs are often not usable out-of-the-box, follow the Nvidia page after installing Hyprland if you plan to use one. Blame NVIDIA for this.

Distros

We officially run and test Hyprland on Arch and NixOS, and we guarantee Hyprland will work there. For any other distro (not based on Arch/Nix) you might have varying amounts of success. However, since Hyprland is extremely bleeding-edge, point release distros like Pop!_OS, Fedora, Ubuntu, etc. will have major issues running Hyprland. Rolling release distros like openSUSE, Solus ,etc. will likely be fine.

Installation

Installing Hyprland is very easy. Simply install it with your package manager.

Warning

It is heavily recommended you use what the distro packages for you, and not compiling manually or using -git packages. Hyprland’s ecosystem and dependencies are vast and intertwined, and compiling manually will only potentially expose you to outdated, or incompatible versions of these dependencies.

If you get .so file mismatch / missing errors, it’s entirely your fault for doing this!

However, if you are an experienced user and want to beta-test new features, you’re more than welcome to run the latest git head. Please don’t come asking about “.so file missing” errors though!

Packages

WARNING: I do not maintain any packages. If they are broken, try building from source first.

Arch

Install a tagged release from the arch packages:

sudo pacman -S hyprland

Compile from source automatically

Warning

Read the warning about using -git packages or compiling from source under Installation first!

Install from the AUR, which compiles the latest source:

yay -S hyprland-git

Alternatively, install the hyprland-meta package to automatically fetch and compile the latest git versions of all components within the hypr* ecosystem.

yay -S hyprland-meta-git

Warning

With -git everytime a direct dependency like hyprutils has an ABI breaking update you need to recompile Hyprland and all other dependent tools. Otherwise you get a “.so not found” error.

If you decide to use the git version from the AUR, you can use the Chaotic Aur to get pre-built binaries. Be aware that updating dependencies like hyprutils might still require you to recompile everything yourself as the Chaotic Aur does not do that automatically.

Note

You can downgrade easily with downgrade to get to a previous -git version.

Nix

Enable Hyprland in your NixOS configuration:

{
  programs.hyprland.enable = true;
}

For more details, read the Nix page.

openSUSE*

Hyprland is part of factory, starting with snapshot 20230411. To install it simply use zypper

sudo zypper in hyprland

or install the “hyprland” package via YaST2 Software.

For hyprpm to recognize it’s dependencies, you’ll also need to install hyprland-devel:

sudo zypper in hyprland-devel

Alternatively, you can also follow the instructions under “Manual (Manual Build)” to build Hyprland yourself.

Note: Hyprland is not available for Leap, as most libraries (and compiler) that Hyprland needs are too old.

Fedora*

lionheartp/Hyprland Copr repository.

You can also compile it yourself by following the instructions here

Debian*

hyprland is available as of Debian 14 (Forky)

sudo apt install hyprland

Note

Hyprland is not available for Bookworm as its packages are too old.

Gentoo*

The hypr packages are available in the hyproverlay. Enable the overlay with:

eselect repository enable hyproverlay
emaint sync -r hyproverlay

Hyprland can be installed with:

emerge --ask gui-wm/hyprland

Additional packages like hyprlock, hypridle, xdg-desktop-portal-hyprland, hyprland-plugins, hyprpaper and hyprpicker are in the overlay. Some of the community-contributed scripts of hyprwm/contrib are also available in their own package (app-misc/grimblast, app-misc/hdrop, etc.) .

emerge --ask gui-apps/hyprlock
emerge --ask gui-apps/hypridle
emerge --ask gui-libs/xdg-desktop-portal-hyprland
emerge --ask gui-apps/hyprpaper
emerge --ask gui-apps/hyprpicker

For USE flags and more details, read the Gentoo wiki page about Hyprland.

FreeBSD*

Hyprland and related are in the default repository:

Ubuntu*

Warning

Ubuntu’s Hyprland is extremely outdated. I do not recommend using the packaged versions at all. Build the entire stack manually instead.

Ubuntu 26.04 LTS (Resolute Raccoon) universe repository

sudo add-apt-repository universe && sudo apt update && sudo apt install hyprland

Ubuntu 24.10 (Oracular Oriole) universe repository

sudo add-apt-repository universe && sudo apt update && sudo apt install hyprland

Void Linux*

Hyprland is not available from Void Linux’s official repositories due to the void developers being salty and personally disliking our main developer. However, a third party repository is available with binary packages built in CI by GitHub Actions.

You can add this repository by creating a file such as /etc/xbps.d/hyprland-void.conf with the following contents:

/etc/xbps.d/hyprland-void.conf

repository=https://raw.githubusercontent.com/Makrennel/hyprland-void/repository-x86_64-glibc

Then you can install the packages as you would any other:

sudo xbps-install -S hyprland
sudo xbps-install -S hyprland-devel # If you want to use plugins
sudo xbps-install -S xdg-desktop-portal-hyprland

xbps-query -Rs hypr # This will require you to have already accepted the repository's fingerprint using xbps-install -S

More information is available in the hyprland-void README, including information about how you can manually build Hyprland for Void Linux using the templates provided.

Slackware*

hyprland-bin (SlackBuilds) - Prebuilt release for Slackware ready for install

Hyprland is not installed by default on the current release of Slackware.

For detailed instructions on installing this build see here

Alpine*

Hyprland is currently available in Alpine’s community repository and it is maintained by the community.

The following command will install hyprland and its dependencies.

apk add hyprland

Ximper*

Install from the Sisyphus:

epmi hyprland
epmi hyprland-devel # If you want to use plugins

Ecosystem:

epmi xdg-desktop-portal-hyprland
epmi hypridle
epmi hyprpaper
epmi hyprpicker

Solus*

For Solus, run:

sudo eopkg install hyprland

* Unofficial, no official support is provided. These instructions are community-driven, and no guarantee is provided for their validity.

Manual

Dependencies:

Note

Please note that Hyprland uses the C++26 standard, so both your compiler and your C++ standard library has to support that (gcc>=15 or clang>=19).

Arch

yay -S ninja gcc cmake meson libxcb xcb-proto xcb-util xcb-util-keysyms libxfixes libx11 libxcomposite libxrender libxcursor pixman wayland-protocols cairo pango libxkbcommon xcb-util-wm xorg-xwayland libinput libliftoff libdisplay-info cpio tomlplusplus hyprlang-git hyprcursor-git hyprwayland-scanner-git hyprwire-git xcb-util-errors hyprutils-git glaze hyprgraphics-git aquamarine-git re2 hyprland-qtutils-git muparser

(Please make a pull request or open an issue if any packages are missing from the list)

openSUSE

zypper in gcc-c++ git meson cmake "pkgconfig(cairo)" "pkgconfig(egl)" "pkgconfig(gbm)" "pkgconfig(gl)" "pkgconfig(glesv2)" "pkgconfig(libdrm)" "pkgconfig(libinput)" "pkgconfig(libseat)" "pkgconfig(libudev)" "pkgconfig(pango)" "pkgconfig(pangocairo)" "pkgconfig(pixman-1)" "pkgconfig(vulkan)" "pkgconfig(wayland-client)" "pkgconfig(wayland-protocols)" "pkgconfig(wayland-scanner)" "pkgconfig(wayland-server)" "pkgconfig(xcb)" "pkgconfig(xcb-icccm)" "pkgconfig(xcb-renderutil)" "pkgconfig(xkbcommon)" "pkgconfig(xwayland)" "pkgconfig(xcb-errors)" glslang-devel Mesa-libGLESv3-devel tomlplusplus-devel

(this should also work on RHEL/Fedora if you remove Mesa-libGLESv3-devel and pkgconfig(xcb-errors))

FreeBSD

pkg install git pkgconf gmake gcc evdev-proto cmake wayland-protocols wayland libglvnd libxkbcommon libinput cairo pango pixman libxcb
pkg install meson jq hwdata libdisplay-info libliftoff
export CC=gcc CXX=g++ LDFLAGS="-static-libstdc++ -static-libgcc"

Ubuntu

Ubuntu 26.04 LTS (Resolute Raccoon)

A build script is available at gitlab.com/kralos/hyprbuntu.

Ubuntu 24.10 (Oracular Oriole)

To install Hyprland from Source, you will need the dependencies below:

sudo apt install -y meson wget build-essential ninja-build cmake-extras cmake gettext gettext-base fontconfig libfontconfig-dev libffi-dev libxml2-dev libdrm-dev libxkbcommon-x11-dev libxkbregistry-dev libxkbcommon-dev libpixman-1-dev libudev-dev libseat-dev seatd libxcb-dri3-dev libegl-dev libgles2 libegl1-mesa-dev glslang-tools libinput-bin libinput-dev libxcb-composite0-dev libavutil-dev libavcodec-dev libavformat-dev libxcb-ewmh2 libxcb-ewmh-dev libxcb-present-dev libxcb-icccm4-dev libxcb-render-util0-dev libxcb-res0-dev libxcb-xinput-dev libtomlplusplus3 libre2-dev

You will also need to build the latest wayland, wayland-protocols, and libdisplay-info tagged releases from source.

For screensharing, you can also install xdg-desktop-portal-wlr or xdg-desktop-portal-hyprland

sudo apt install -y xdg-desktop-portal-wlr

Unfortunately, xdg-desktop-portal-hyprland still not in Ubuntu Repo so you have to build it from source

See The xdph GitHub repo’s readme. Refer to XDPH and Ubuntu Guide For Installing And Building Hyprland Gist for more information.

Warning

Please note that since Ubuntu is generally behind with dependencies, it’s not guaranteed that the build process will work at all. Even if it is, it’s likely that it will break at some point in the future.

Warning

Always use the latest version of Ubuntu for the most up to date dependencies.

Note: Your mileage may vary, as GDM has some bugs with Hyprland. Check the Master Tutorial for more info.

Refer to the gist if anything fails.

Warning

Additionally to those, you will also need a few hypr* dependencies which may or may not be packaged for your distro of choice:

aquamarine
hyprlang
hyprcursor
hyprutils
hyprgraphics
hyprwayland-scanner (build-only)

CMake (recommended)

git clone --recursive https://github.com/hyprwm/Hyprland
cd Hyprland
make all && sudo make install

CMake is always recommended as it’s the intended way Hyprland should be installed.

Crash on launch

See Crashes and Bugs.

Custom installation (debug build, etc)

cd into the hyprland repo.
for debug build:

make debug
sudo make install

Any other config: (replace <PRESET> with your preset: release, debug)

make <PRESET> && sudo cp ./build/Hyprland /usr/bin && sudo cp ./example/hyprland.desktop /usr/share/wayland-sessions

Custom Build flags

To apply custom build flags, you’ll have to ditch make.

Supported custom build flags on CMake:

NO_XWAYLAND - Removes XWayland support
NO_SYSTEMD - Removes systemd dependencies
NO_UWSM - Does not install the hyprland-uwsm.desktop file
NO_HYPRPM - Does not build and install hyprpm

Flags can be passed to CMake like this:

cmake --no-warn-unused-cli -DCMAKE_BUILD_TYPE:STRING=Release -D<FLAG>:STRING=true -B build

Change <FLAG> to one of the custom build flags. Multiple flags can be used at once, by adding more -D<FLAG_2>:STRING=true.

The BUILD_TYPE can also be changed to Debug.

To build, run:

cmake --build ./build --config Release --target all -j`nproc 2>/dev/null || getconf NPROCESSORS_CONF`

If you configured in Debug, change the --config to Debug as well.

To install, run:

sudo cmake --install ./build

Running In a VM

YMMV, this is not officially supported.

Read through the libvirt Arch wiki page and get libvirt, virsh, and virt-viewer setup and installed.

# Install libvirt and qemu things.
sudo pacman -S libvirt virt-viewer qemu-common
# Add yourself to the libvirt group.
sudo usermod -a -G libvirt USER # Replace 'USER' with your username.
# Enable and start libvirtd.
systemctl enable --now libvirtd

Go to the arch-boxes gitlab and download the latest arch qemu basic image. You can also download via any of arch’s mirrors.

curl https://geo.mirror.pkgbuild.com/images/latest/Arch-Linux-x86_64-basic.qcow2 \
  -o ~/Downloads/arch-qemu.qcow2 # Or download wherever you want.

Create the VM with virsh.

# Use virt-install (included with libvirt) to install the vm from the image.
virt-install \
  --graphics spice,listen=none,gl.enable=yes,rendernode=/dev/dri/renderD128 \
  --name hypr-vm \
  --os-variant archlinux \
  --memory 2048 \
  --disk ~/Downloads/arch-qemu.qcow2 \
  --import

Connect with virt-viewer, this will open a virt-viewer graphical session on the tty. The default login is ‘arch’ for user and ‘arch’ for password.

Warning

Make sure the –attach flag is used, enabling virgl makes it so that we had to disable listen. This means that we can’t make a direct TCP/UNIX socket connection to the remote display. –attach asks libvirt to provide a pre-connected socket to the display.*

virt-viewer --attach hypr-vm

Finally on the guest follow the instructions above for either installing hyprland-git from the aur or building manually.

Warning

Make sure you install mesa as the OpenGL driver. The virgl drivers are included in mesa.

Last updated on April 29, 2026

Master tutorial