How to Build Hyprland from Source: Complete Installation Guide

To build Hyprland from source, install a C++ toolchain and Wayland dependencies, clone the hyprwm/Hyprland repository, configure the build with meson setup build, compile with ninja -C build, and optionally install system-wide using sudo ninja -C build install.

Hyprland is a modern, dynamic tiling Wayland compositor written in C++ that operates independently of the traditional wlroots stack. According to the hyprwm/Hyprland source code, the project implements its own rendering pipeline in src/Renderer.cpp and compositor core in src/Compositor.hpp, making the build process dependency-specific but straightforward using Meson.

Prerequisites for Building Hyprland

Building Hyprland requires a recent C++ toolchain, the Meson build system, and several Wayland-related development libraries. Because the project deliberately avoids wlroots dependencies, you only need standard Wayland headers and graphics libraries specified in the root meson.build file.

Arch Linux

sudo pacman -S base-devel meson ninja git wayland wayland-protocols libdrm libinput libxkbcommon libinput xf86-input-evdev cairo pango libevdev pixman

Debian and Ubuntu

sudo apt install build-essential meson ninja-build git libwayland-dev wayland-protocols libdrm-dev libinput-dev libxkbcommon-dev libxcb1-dev libxcb-xinput0-dev libxcb-composite0-dev libxcb-damage0-dev libxcb-render0-dev libxcb-ewmh-dev libxcb-icccm4-dev libxcb-xfixes0-dev libxcb-image0-dev libxcb-randr0-dev libxcb-util0-dev libcairo2-dev libpango1.0-dev libpixman-1-dev libevdev-dev

Fedora

sudo dnf install @development-tools meson ninja-build git wayland-devel wayland-protocols-devel libdrm-devel libinput-devel libxkbcommon-devel libxcb-devel cairo-devel pango-devel pixman-devel libevdev-devel

Step-by-Step Build Process

The source code uses Meson for configuration and Ninja for compilation. The meson.build file in the repository root handles dependency detection, compiler flags, and optional feature toggles like fmt and spdlog support.

First, clone the repository:

git clone https://github.com/hyprwm/Hyprland.git
cd Hyprland

Create a Meson build directory:

meson setup build

This command detects optional dependencies and enables corresponding features. You can explicitly disable features using -Dfeature_name=disabled if needed.

Compile the source:

ninja -C build

This produces the binary at build/Hyland.

Optionally install system-wide:

sudo ninja -C build install

Running Hyprland After Building

After building, you can run the compositor directly from the build directory without installing.

To test immediately:

./build/Hyprland

To launch from a TTY:

exec Hyprland

Hyprland reads its configuration from ~/.config/hypr/hyprland.conf upon startup. The compositor's architecture uses src/Compositor.hpp for the Wayland server implementation managing client connections and global objects, while src/Renderer.cpp handles the OpenGL/EGL rendering pipeline with shaders for effects like blur and shadows.

Debugging Build and Runtime Issues

For development or troubleshooting issues in subsystems like the input handler (src/InputManager.cpp) or IPC layer (src/IPC.cpp), enable verbose debugging.

Enable debug symbols in Meson:

meson configure -Ddebug=true build

Run with verbose logging:

HYPR_DEBUG=1 ./build/Hyprland

The meson.build configuration supports various build options that control feature compilation. Review available options with meson configure build to see toggles for optional dependencies.

Plugin Development Context

If extending Hyprland, note that the plugin system in src/Plugin.cpp loads external shared objects at runtime via dlopen. Plugins reside in ~/.config/hypr/plugins/ and interface with the window management logic in src/Window.hpp.

A minimal plugin skeleton:

#include <hyprutils/signal/Signal.hpp>
#include <hyprland/src/Plugin.hpp>

HYPR_PLUGIN_EXPORT
void HyprPluginInit() {
    // Register custom layouts or IPC commands here
}

Compile with:

g++ -shared -fPIC -o myplugin.so myplugin.cpp $(pkg-config --cflags --libs hyprland)

Load by placing the .so file in the plugins directory and running hyprctl reload.

Summary

• Hyprland builds from source using Meson and Ninja, deliberately excluding wlroots dependencies.
• Required development headers include wayland-protocols, libdrm, libinput, libxkbcommon, cairo, and pango.
• Run meson setup build followed by ninja -C build to produce the build/Hyprland binary.
• The compositor configuration resides at ~/.config/hypr/hyprland.conf.
• Key architectural files include src/Compositor.hpp (server core), src/Renderer.cpp (OpenGL rendering), and src/IPC.cpp (socket-based control interface).

Frequently Asked Questions

Does Hyprland require wlroots to build?

No. According to the source code in src/Compositor.hpp, Hyprland implements its own Wayland server logic and deliberately avoids the wlroots stack. You only need standard Wayland development headers (wayland-devel or libwayland-dev) and the wayland-protocols package.

Can I build Hyprland without installing it system-wide?

Yes. After running ninja -C build, you can execute ./build/Hyprland directly from the repository directory. This allows testing modifications without overwriting your system installation or affecting other users.

What optional features does Meson configure automatically?

The meson.build file automatically detects and enables features based on available libraries, including fmt and spdlog for enhanced logging. You can view and modify these options using meson configure -Dfeature_name=disabled build before compiling.

Where does Hyprland read its configuration after building from source?

Hyprland reads configuration from ~/.config/hypr/hyprland.conf at startup. This path is consistent regardless of whether you run the binary directly from build/Hyprland or install it system-wide. The configuration directory also hosts runtime plugins in the plugins/ subdirectory.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}