# How to Build Hyprland from Source: Complete Installation Guide

> Build Hyprland from source with our comprehensive guide. Learn to install dependencies, compile, and configure Hyprland for a custom Wayland experience.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: how-to-guide
- Published: 2026-07-29

---

**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`](https://github.com/hyprwm/Hyprland/blob/main/src/Renderer.cpp) and compositor core in [`src/Compositor.hpp`](https://github.com/hyprwm/Hyprland/blob/main/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

```bash
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

```bash
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

```bash
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:

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

```

Create a Meson build directory:

```bash
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:

```bash
ninja -C build

```

This produces the binary at `build/Hyland`. 

Optionally install system-wide:

```bash
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:

```bash
./build/Hyprland

```

To launch from a TTY:

```bash
exec Hyprland

```

Hyprland reads its configuration from `~/.config/hypr/hyprland.conf` upon startup. The compositor's architecture uses [`src/Compositor.hpp`](https://github.com/hyprwm/Hyprland/blob/main/src/Compositor.hpp) for the Wayland server implementation managing client connections and global objects, while [`src/Renderer.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/src/InputManager.cpp)) or IPC layer ([`src/IPC.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/IPC.cpp)), enable verbose debugging.

Enable debug symbols in Meson:

```bash
meson configure -Ddebug=true build

```

Run with verbose logging:

```bash
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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/src/Window.hpp).

A minimal plugin skeleton:

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

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

```

Compile with:

```bash
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`](https://github.com/hyprwm/Hyprland/blob/main/src/Compositor.hpp) (server core), [`src/Renderer.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/Renderer.cpp) (OpenGL rendering), and [`src/IPC.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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.