Hyprland Quick-Start Guide: Setting Up a Modern Tiling Window Manager on Linux

Hyprland is a dynamic tiling window manager built for the modern Wayland display server protocol. In this guide, we’ll walk you through the process of setting up Hyprland on your Linux system.

Why Wayland?

First and foremost, performance and reduced input lag. Wayland is a modern replacement for X11, and it has much cleaner architecture, better application separation, and improved HiDPI hardware support.

What is a Tiling Window Manager and Why Should I Care?

So, a tiling window manager, as opposed to a floating window manager, organizes your windows in a non-overlapping, grid-like pattern. It will give you a superhuman ability to fly through your windows and workspaces with hotkeys and improve your productivity.

Before We Begin

Prerequisites

• You’re assumed to have a basic Linux knowledge.
• A Linux distribution (preferably Arch Linux or an Arch-based distro).
• Basic knowledge of terminal commands.
• Administrative (sudo) privileges.

Important Note for NVIDIA GPU Users

If you’re using an NVIDIA GPU, you’ll need to enable nvidia_drm for proper compatibility with Wayland and Hyprland.

Step 1: Modify GRUB_CMDLINE_LINUX_DEFAULT

In your GRUB configuration file: /etc/default/grub add nvidia_drm.modeset=1 at the end of the GRUB_CMDLINE_LINUX_DEFAULT line:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash nvidia_drm.modeset=1"

Step 2: Update GRUB

sudo grub-mkconfig -o /boot/grub/grub.cfg

Step 3: Reboot Your System

sudo reboot

Installing Hyprland

Step 1: Update Your System

First things first, make sure your system is up to date:

sudo pacman -Syu

Step 2: Install Essential Applications

We’ll need a few applications before installing Hyprland.

Install Kitty Terminal Emulator

Hyprland uses Kitty as its default terminal emulator. You can change this in the configuration file.

sudo pacman -S kitty

Install Dolphin File Manager

For file management, we’ll use Dolphin. Also can be changed in the configuration file.

sudo pacman -S dolphin

Step 3: Install Hyprland

Now, let’s install Hyprland itself:

sudo pacman -S hyprland

Step 4: install Qt-Wayland

In order to have Qt applications render properly in Hyprland, we need to install Qt-Wayland.

sudo pacman -S qt5-wayland qt6-wayland

Launching Hyprland for the First Time

Step 1: Log Out of Your Current Session

Save any work and log out.

Step 2: Select Hyprland at Login

On the login screen, choose Hyprland from the session options.

Step 3: Log In

Enter your credentials.

Step 4: Initial Configuration

You might see a warning about an autogenerated config. Let’s fix that.

• Press Super + Q (the “Super” key is usually the Windows key) to open Kitty.

• Open the configuration file ~/.config/hypr/hyprland.conf in your text editor:

• Remove or comment out the line:

  autogenerated=1
  

• Save and exit.

Inside the configuration file, there are some variables that are already have set up, like $terminal, $fileManager, $menu etc. You can change them as needed to your preference, but we’ll leave them as is for the purpose of this guide.

There is also a $mainMod variable set to SUPER, which corresponds to your Windows key. You can change it as well, but we’ll assume it stays SUPER.

Configuring for HiDPI Monitors

If you’re using a HiDPI (4K) monitor, you might notice that everything looks tiny.

Step 1: Identify Your Monitor

hyprctl monitors -j

Note the name of your monitor (e.g., DP-1).

Step 2: Edit the Configuration File

In your ~/.config/hypr/hyprland.conf add or modify the monitor line:

monitor=DP-1,preferred,auto,1.5

Adjust the scaling factor (1.5) as needed.

Step 3: Add Environment Variables

# Environment Variables
env = XDG_CURRENT_DESKTOP,Hyprland
env = XDG_SESSION_TYPE,wayland
env = XDG_SESSION_DESKTOP,Hyprland
env = ELECTRON_OZONE_PLATFORM_HINT,wayland

And if you have NVIDIA GPU, you should also add:

env = LIBVA_DRIVER_NAME,nvidia
env = GBM_BACKEND,nvidia-drm
env = __GLX_VENDOR_LIBRARY_NAME,nvidia
env = NVD_BACKEND,direct

Step 4: Reload Configuration

Hyprland should automatically reload the config. If not, manually reload:

hyprctl reload

Installing Wofi - A Program Launcher

We need a way to launch applications easily.

Step 1: Install Wofi

sudo pacman -S wofi

Step 2: Configure Hyprland to Use Wofi

In your ~/.config/hypr/hyprland.conf you should already have the $menu = wofi --show drun and bind = $mainMod, R, exec, $menu lines. If not, add them.

# In ~/.config/hypr/hyprland.conf
$menu = wofi --show drun
bind = $mainMod, R, exec, $menu

Step 3: Test Wofi

Press Super + R and try launching an application like dolphin.

Navigating and Managing Windows in Hyprland

• Switch Between Windows: Super + Arrow Keys
• Move Windows using the Mouse: Hold Super and drag the window.
• Switch Workspaces: Super + [Workspace Number]
• Move Windows to Another Workspace: Super + Shift + [Workspace Number]

Installing and Configuring Waybar - A Status Bar

Waybar provides a customizable status bar.

Step 1: Install Waybar

sudo pacman -S waybar

Step 2: Install Required Fonts

sudo pacman -S ttf-font-awesome

Step 3: Copy Default Configuration

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

Step 4: Edit the Configuration File

Inside the ~/.config/waybar/config.jsonc file you can find a bunch of modules, for the left, center, and right side of the status bar. What we need to do is to remove the unnecessary ones and add our own(e.g. custom/power). Waybar’s default config will come with a buch of sway-related modules; let’s repalce sway with hyprland for the ones we want to use. You can peak and choose your own set of modules. However, my modules look like this:

"modules-left": ["hyprland/workspaces"],
"modules-center": ["hyprland/window"],
"modules-right": [
   "pulseaudio",
   "power-profiles-daemon",
   "cpu",
   "memory",
   "temperature",
   "backlight",
   "hyprland/language",
   "battery",
   "clock",
   "custom/power",
   "tray"
],

Configure hyprland/workspaces Module

Now let’s configure the hyprland/workspaces module to indicate the active workspace.

"hyprland/workspaces": {
    "disable-scroll": true,
    "all-outputs": true,
    "warp-on-scroll": false,
    "format": "{icon}",
    "format-icons": {
        "urgent": "",
        "active": "",
        "default": ""
    }
},

Since I have an issue currently with rendering fontawsome here, I will just add an image here alongside the copieble text:

Configure hyprland/language Module

"hyprland/language": {
    "format": "{short}",
    "tooltip": false
},

Step 5: Configure Keyboard Layouts in Hyprland

Let’s add multiple keyboard layouts for our language module in the ~/.config/hypr/hyprland.conf file, change the following lines:

# In ~/.config/hypr/hyprland.conf
input {
 kb_layout = us,de
 kb_options = grp:win_space_toggle
}

This will set the switch between layouts to Super + Space.

Step 6: Autostart Waybar

# In ~/.config/hypr/hyprland.conf
exec-once = waybar

Step 7: Reload Configuration

the exac-once won’t start waybar until you restart Hyprland, but you can run it for now by simply running:

waybar & disown

then to restart it again:

killall waybar
waybar & disown

we will need this later on, when we’re adding power management features and power menu.

Notifications on Hyprland

To have notifications on Hyprland we’ll use mako the lightweight notification daemon for Wayland.

sudo pacman -S mako

That’s it. Notifications should appear in the top right corner of your screen by default.

If for some reason it is not stated with systemd, you can add it to ~/.config/hypr/hyprland.conf:

# In ~/.config/hypr/hyprland.conf
exec_once = mako

Adding and Configuring Lock Screen, Wallpaper, and Idle Lock

Step 1: Install hyprlock and hyprpaper

We’ll use:

• hyprlock: A simple lock screen utility designed for Hyprland.
• hyprpaper: A wallpaper utility that integrates seamlessly with Hyprland.
• hypridle: A simple idle timer for Hyprland.

Let’s start by installing the necessary packages.

sudo pacman -S hyprlock hyprpaper hypridle

Step 2: Configure hyprpaper for Wallpapers

Create a Wallpaper Directory

First, decide where you want to store your wallpapers. Let’s create a directory in your home folder.

mkdir -p ~/Pictures/Wallpapers

Place your desired wallpaper images in this directory. I’ve got mine from here

Edit Hyprland Configuration for hyprpaper

Open your Hyprland configuration file ~/.config/hypr/hyprland.confin your favorite text editor and add the following line to start hyprpaper:

# Wallpaper Configuration
exec-once = hyprpaper

This line ensures that hyprpaper starts when Hyprland launches.

Configure hyprpaper

Create a configuration file for hyprpaper ~/.config/hypr/hyprpaper.conf and add the following content:

preload = ~/Pictures/Wallpapers/25562.jpg

# Set wallpaper for each monitor
wallpaper = ,~/Pictures/Wallpapers/25562.jpg

• Replace 25562.jpg with the filename of your wallpaper.
• The empty comma applies the wallpaper to all monitors. If you have multiple monitors and want different wallpapers, specify each monitor separately e.g.

wallpaper = Monitor1,~/Pictures/Wallpapers/wallpaper1.jpg
wallpaper = Monitor2,~/Pictures/Wallpapers/wallpaper2.jpg

Test hyprpaper

• Restart Hyprland or logout and log back in.

Your wallpaper should now be displayed.

Step 3: Configure hyprlock for Lock Screen

Bind a Key to Lock the Screen

We’ll set up a keybinding to lock the screen using hyprlock.

Open your Hyprland configuration file ~/.config/hypr/hyprland.conf and add the following line to bind Super + L to lock the screen:

# Lock Screen
bind = SUPER,L,exec,hyprlock

Customize hyprlock

Hyprlock is minimal by default. Let’s customize it a bit. First let’s put a background image in our ~/Pictures/Wallpapers directory, it should be in PNG format. Let’s save it as lock_wallpaper.png. I grabbed mine from here.

Next, we need to create a configuration file for hyprlock in ~/.config/hypr/hyprlock.conf and add the following content:

# Lock Screen Configuration
general {
    grace = 1
}

background {
    monitor =
    path = $HOME/Pictures/Wallpapers/lock_wallpaper.png  # NOTE only png supported for now

    # all these options are taken from hyprland, see https://wiki.hyprland.org/Configuring/Variables/#blur for explanations
    blur_size = 5
    blur_passes = 1 # 0 disables blurring
    noise = 0.0117
    contrast = 1.3000 # Vibrant!!!
    brightness = 0.8000
    vibrancy = 0.2100
    vibrancy_darkness = 0.0
}

input-field {
    monitor =
    size = 250, 50
    outline_thickness = 3
    dots_size = 0.33 # Scale of input-field height, 0.2 - 0.8
    dots_spacing = 0.15 # Scale of dots' absolute size, 0.0 - 1.0
    dots_center = true
    outer_color = $color5
    inner_color = $color0
    font_color = $color12
    #fade_on_empty = true
    placeholder_text = <i>Password...</i> # Text rendered in the input box when it's empty.
    hide_input = false
    
    position = 0, 200
    halign = center
    valign = bottom
}

• background element is for the background image.
• input-field element is for the password input field on the lock screen.

This is very basic lock screen configuration. To dig into more detail, check out the Hyprlock documentation.

Save and Test hyprlock

• Save the configuration file.

• Reload Hyprland:

  hyprctl reload
  

• Press Super + L to test the lock screen.

Step 4: Configure hypridle for Idle Timer

Configure hypridle

Open your Hyprland configuration file ~/.config/hypr/hyprland.conf and add the following lines to start up hypridle:

# Idle Timer Configuration
exec-once = hypridle

This line ensures that hypridle starts when Hyprland launches.

Next, we’ll need to create a configuration file for hypridle in ~/.config/hypr/hypridle.conf and add the following content:

# Idle Timer Configuration
general {
    lock_cmd = pidof hyprlock || hyprlock       # avoid starting multiple hyprlock instances.
    before_sleep_cmd = loginctl lock-session    # lock before suspend.
    after_sleep_cmd = hyprctl dispatch dpms on  # to avoid having to press a key twice to turn on the display.
}

listener {
    timeout = 150                                # 2.5min.
    on-timeout = brightnessctl -s set 10         # set monitor backlight to minimum, avoid 0 on OLED monitor.
    on-resume = brightnessctl -r                 # monitor backlight restore.
}

listener {
    timeout = 300                                # 5min
    on-timeout = loginctl lock-session           # lock screen when timeout has passed
}

listener {
    timeout = 330                                 # 5.5min
    on-timeout = hyprctl dispatch dpms off        # screen off when timeout has passed
    on-resume = hyprctl dispatch dpms on          # screen on when activity is detected after timeout has fired.
}

listener {
    timeout = 600                                 # 10min
    on-timeout = systemctl suspend                # suspend pc
}

Test hyprpaper

• Restart Hyprland or logout and log back in.

Adding Power Management Features

Installing power-profiles-daemon

Step 1: Install the Daemon

sudo pacman -S power-profiles-daemon

Step 2: Enable and Start the Service

sudo systemctl enable power-profiles-daemon.service
sudo systemctl start power-profiles-daemon.service

Configuring the Power Menu in Waybar

We will use wofi to create the power menu.

Step 1: Edit Waybar Configuration

Make sure you have custom/power in your modules-right in the waybar config file.

"custom/power": {
   "format" : "⏻ ",
   "tooltip": false,
   "on-click": "~/.config/waybar/powermenu.sh",
}

Step 2: Create the Execution Script

Create a script ~/.config/waybar/powermenu.sh with the following content:

#!/usr/bin/env bash

op=$( echo -e "  Poweroff\n  Reboot\n  Suspend\n Hibernate\n  Lock\n  Logout" | wofi -i --dmenu --width 300 --height 215 | awk '{print tolower($2)}' )

case $op in 
poweroff)
   ;&
reboot)
   ;&
hibernate)
   ;&
suspend)
   echo "systemctl $op"
   systemctl $op
   ;;
lock)
   hyprlock
   ;;
logout)
   hyprctl dispatch exit
   ;;
esac

Make it executable:

chmod +x ~/.config/waybar/powermenu.sh

Step 3: Restart Waybar

killall waybar
waybar & disown

Adding Network Manager Applet

Manage your network connections easily.

Step 1: Install network-manager-applet

sudo pacman -S network-manager-applet

Step 2: Autostart nm-applet

# In ~/.config/hypr/hyprland.conf
exec-once = nm-applet

Wrapping Up

That’s it for now. This is a very basic Hyprland setup. You can find more advanced configurations in the Hyprland documentation.

Here we use the following components:

• Hyprland: A modern tiling window manager.
• Waybar: A customizable status bar.
• Wofi: A program launcher.
• Dolphin: A feature-rich file manager.
• Hyprpaper: A wallpaper manager.
• Hyprlock: A screen locker.
• Hypridle: A idle service for Hyprland.
• Power Management: A custom power menu in Waybar.
• Network Manager Applet: For easy network management.

Happy Tiling!

Disclaimer: This guide is provided for educational purposes. Please ensure you have backups and understand each step before proceeding.