Skip to content
Getting Started
Installation

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 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.

It is heavily recommended you use what the distro packages for you, not compiling manually nor 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

The Hypr* team does not maintain any packages. If they are broken, try building from source first.

Distributions marked with * are not officially supported. These instructions are community-driven, and no guarantee is provided for their validity.

Install a tagged release from the Arch repositories:

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-git 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 version, every time 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.

Manual build

Dependencies:

Warning

Never, under any circumstances, symbolically link different .so versions together, this will lead to memory bugs and crashes. We don’t care what some random person from the Internet tells you that. Do not do it.

Important

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

If any packages are missing from the list, make a pull request or open an issue in wiki repository.

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

The order in which you must build is:

Lua
hyprland-protocols
hyprwayland-scanner
hyprutils
hyprgraphics
hyprlang
hyprcursor
aquamarine
xdg-desktop-portal-hyprland
hyprwire
hyprtoolkit
hyprland

Other packages from hypr* stack (e.g., hyprlock, hyprsunset, etc.) can be built in any order after Hyprland.

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.)

  1. cd into the Hyprland repo
  2. For debug build:
    make debug
sudo make install
  3. 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, which will open a graphical session on the TTY. The default login is arch for both the user and its 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
Master tutorial