How to Install and Configure Hyprland (Wayland) on Arch Linux

With the steady adoption of the Wayland display server protocol, Linux users looking for a modern and dynamic window manager often turn to Hyprland. Hyprland is a feature-rich and actively developed Wayland compositor that offers an eye-catching, dynamic tiling experience and a range of advanced features such as animations, gestures, and per-window rules.

In this guide, we’ll walk through the steps to install and configure Hyprland on Arch Linux, making sure everything from dependencies to user experience is carefully covered. By the end, you’ll have a sleek and customizable Wayland environment up and running.

1. Prerequisites

Before installing Hyprland, ensure your Arch system is up to date:

sudo pacman -Syu

You’ll also want:

• A Wayland-compatible GPU driver (Intel, AMD, or NVIDIA with proprietary driver ≥ 515)
• A functional audio and network setup (e.g., PipeWire, NetworkManager)
• Some familiarity with editing configuration files and managing services on Arch

Optional but helpful tools include git, yay (for AUR packages), and neovim or nano for editing.

2. Installing Hyprland

Hyprland is available in the Arch User Repository (AUR). You can use an AUR helper like yay or install manually using git.

Installing via yay

yay -S hyprland-git

This package pulls the latest bleeding-edge development version from GitHub. If you prefer a more stable release, you can use:

yay -S hyprland

Note: Hyprland is actively developed, so hyprland-git may include new features (and bugs).

Installing dependencies

If not already installed:

sudo pacman -S base-devel git

3. Installing Required Dependencies

Hyprland is just the compositor—you’ll also need:

Essential tools

sudo pacman -S xdg-desktop-portal-hyprland xwayland wlroots \
              wayland-utils wayland-protocols

Input and clipboard tools

sudo pacman -S wl-clipboard xdg-utils

Notification daemon

sudo pacman -S mako

Terminal emulator

sudo pacman -S foot

File manager

sudo pacman -S thunar

Wallpaper utility

sudo pacman -S swww

You can replace foot and thunar with your preferred terminal and file manager.

4. Creating a Hyprland User Configuration

Hyprland stores configuration files in ~/.config/hypr/. Start by creating this directory and copying the default config:

mkdir -p ~/.config/hypr
cp /usr/share/hyprland/examples/hyprland.conf ~/.config/hypr/hyprland.conf

Editing the Configuration

Open the config:

nano ~/.config/hypr/hyprland.conf

You’ll find sections for keybindings, monitor setup, window rules, animations, and more.

Here are a few key changes you might want to make:

Set Your Preferred Terminal

$terminal = foot

Set Wallpaper with swww

Add to the exec-once section:

exec-once = swww init && swww img /path/to/wallpaper.jpg

Set Your Notification Daemon

exec-once = mako

Launch Status Bar

(If using Waybar, see next section.)

exec-once = waybar

5. Installing a Status Bar (Waybar)

Hyprland does not include a built-in bar, so many users opt for Waybar, which supports modules for battery, CPU, network, etc.

Install Waybar

sudo pacman -S waybar

Then create the config:

mkdir -p ~/.config/waybar
cp /etc/xdg/waybar/config ~/.config/waybar/
cp /etc/xdg/waybar/style.css ~/.config/waybar/

Customize

You can edit the configuration files to add modules or change colors. Waybar integrates well with hyprland using the hyprland module.

6. Adding a Login Manager (Optional)

You can start Hyprland from a TTY or via a Wayland-compatible login manager.

Manual (TTY) Launch

Edit ~/.bash_profile or ~/.zprofile and add:

[[ -z $DISPLAY && $XDG_VTNR -eq 1 ]] && exec Hyprland

Using SDDM or greetd

SDDM is a graphical login manager that supports Wayland sessions.

Install it:

sudo pacman -S sddm

Then enable:

sudo systemctl enable sddm

Create a desktop session file if it’s missing:

# /usr/share/wayland-sessions/hyprland.desktop
[Desktop Entry]
Name=Hyprland
Exec=Hyprland
Type=Application

7. Useful Tools for Hyprland

To enhance your experience, consider installing:

Install them using sudo pacman -S or yay -S depending on whether they are in the official repos or AUR.

8. Tips for Troubleshooting

Session fails to start?

• Check .bash_profile or login manager session config.
• Use journalctl -xe or ~/.local/share/hyprland/hyprland.log for logs.

Black screen?

• Make sure your wallpaper tool (swww) or status bar (waybar) is not crashing.
• Try launching Hyprland without exec-once apps.

Input devices not working?

• Install libinput and confirm devices are detected with libinput list-devices.

Nvidia issues?

• Ensure you’re using proprietary drivers (≥ version 515).
• Add the following to your Hyprland config:

env = WLR_NO_HARDWARE_CURSORS,1

9. Final Thoughts

Installing and configuring Hyprland on Arch Linux offers a powerful, modern desktop experience for users who enjoy customization and speed. While Hyprland is still evolving, it’s already capable of replacing more traditional desktop environments for many users.

The key to a successful setup is understanding how the Wayland ecosystem differs from X11. With tools like waybar, swww, and rofi-wayland, you can craft a beautiful and efficient desktop tailored to your needs.

Don’t be afraid to dive into configuration files and experiment. That’s the Arch and Hyprland way.

Useful Resources:

• Hyprland GitHub Repository
• Hyprland Wiki
• Arch Wiki: Hyprland