Customizing Hyprland to Your Liking

So, you have installed Hyprland and now want to enjoy it the neat tiling window experience along with the eye candy effects?

Hyprland is highly customizable and the project gives you a very comprehensive user manual.

I understand that you may not want to go through all that, specially in the beginning, and hence I am sharing some basic Hyprland configuration to act as a beginner’s guide.

📋

This article assumes that you have installed the vanilla Hyprland. Those who installed Hyprland using some others dot files may not require all the steps mentioned in this article.

1. Remove the autogenerated configuration warning

The first thing you notice when you log into a newly installed Hyprland system is a warning stating “You are using the autogenerated configuration file”.

To remove it, open the Hyprland configuration file.

nano ~/.config/hypr/hyprland.config

Now, remove the line:

autogenerated = 1

It appears at the very beginning of the file. Once removed, save the file to see the effect immediately.

💡

The configuration file of Hyprland is located at /home/$USER/.config/hypr/hyprland.config.

2. Use Hyprpaper for wallpapers

If you installed Hyprland using the archinstall script, chances are there that you have no wallpaper.

At first, I thought my installation was a failure because when logged in, there was this autogenerated config warning and a pitch-black screen.

In Hyprland, you can use the Hyprpaper utility to set wallpapers. It lets you set wallpaper to multiple screens, along with other cool features.

Install Hyprpaper in Arch Linux using the command:

sudo pacman -Syu hyprpaper

Once installed, look for the configuration file at ~/.config/hypr/hyprpaper.conf. If it is not there, create it and open it.

nano ~/.config/hypr/hyprpaper.conf

Open a new terminal and run the command:

hyprctl monitors

📋

From here on, when I say list monitors, it implies hyprctl monitors.

Since I am using Hyprland inside GNOME Boxes, my monitor name will be Virtual-1.

Inside the Hyprpaper config, preload the wallpaper and apply the wallpaper:

preload = <Path to the wallpaper>

# wallpaper = <Monitor-name>, <path to wallpaper>
wallpaper = Virtual-1, /home/team/Pictures/wallpaper.png

📋

All wallpapers you want to set, need to be preloaded. At the same time, limit the number of images to a bare minimum to avoid memory usage.

Once the configuration is done, save the file and exit. Now, open the Hyprland config and enter the line:

exec-once hyprpaper

📋

The exec-once keyword is used to define apps, that should be started when Hyprland is started. You can autostart multiple apps with one exec-once command by using the & operator.

You need to relogin to Hyprland to see the effect.

💡

Use the shortcut Super+M to quit the Hyprland session to the login screen.

3. Configure monitors

This is more suitable for dual or multi-monitor setup.

First list the monitors and get the name of the monitors you have connected. Once you have the names, open the Hyprland config and add the line in MONITORS section:

# monitor=<monitor_name>,<resolution>@fps,<position>,<scaling>

monitor=Virtual-1,1920x1080@60,0x0,1.5

In this config, the <position> is the place where your current monitor appear in a multi-monitor setup. This means that if you have a monitor with resolution 3860×2160 and another 1920×1080, then the position of the second monitor can be 3860×0 to make it right of the first.

monitor=monitor2-name,1920x1080@60,3860x0,1

💡

Position value accepts negative value as well, like -1080. This is useful to place one monitor above another.

The value depends on scaling. So, instead of going blindly, you may need to apply some logic about your monitor scaling, orientation, and positioning.

4. Add a panel

Panel is an essential part in any window/desktops. All the essential utilities like taskbar, system tray, workspace indicators, etc. are placed here.

You can use panel/bar applications like Waybar with Hyprland.

🚧

Hyprland is purely Wayland. So consider using a Wayland panel application.

We have a detailed guide on installing and configuring Waybar. Refer to it for more information.

5. Set a notification daemon

Popular desktop environments like GNOME, KDE Plasma, etc. take care of this part automatically. In Hyprland, you need to configure it manually and you SHOULD do it.

Without a notification daemon, you will miss a vital part of modern desktop computing experience.

For me, dunst, a highly customizable notification daemon was installed automatically, and I decided to stick with that. You can install the same using:

sudo pacman -Syu dunst

Once dunst is installed, verify by sending a test notification:

notify-send "Hello World!"

Yes, it is working. If not, try autostarting it in the Hyprland config:

exec-once dunst

And relogin to the system.

6. Clipboard manager

Clipboard managers are a must for any system. I suggest using CopyQ, a simple and powerful clipboard utility.

There isn’t much to do. Install Copyq using:

sudo pacman -Syu copyq

Autostart it in the Hyprland config:

exec-once copyq --start-server

Now, go to the Copyq File → Preferences and select the Hide Main Window option in Layout tab.

7. Set Hyprshot, the screenshot utility

Who don’t want to share their Hyprland setup to the community? To take a screenshot, you need a tool. Hyprshot is the one for you.

🚧

In order for the Hyprshot to work properly, you should have the notification daemon configured. Daemon configuration is mentioned earlier.

To install Hyprshot, ensure you have all the dependencies installed. In Arch Linux, run:

sudo pacman -Syu jq grim slurp wl-clipboard libnotify

Now, install the Hyprshot from AUR. You can use AUR helpers like Yay here.

yay -S hyprshot

Or follow the traditional AUR installation methods.

If you are in other distributions, go over to Hyprshot GitHub page and download the script from releases. Place it in any directory that is in your PATH.

Now, scroll down to the KEYBINDINGS section in the Hyprland config file and add the line to the end of the section.

# Screenshot a window
bind = , PRINT, exec, hyprshot -m region

💡

You might have noted a comma at the beginning. This means no modifier key like SUPER is used. Just press the PrtScr key. If you need to use SUPER_PrtScr, place SUPER before the comma. bind = SUPER, PRINT, exec, hyprshot -m region.

This will bind the PrtScr key to take a screenshot of a region that you select.

The file, by default, will be saved to the ~/Pictures folder.

Instead of hyprshot -m region, you can use hyprshot -m region --clipboard-only to copy the image to clipboard instead of saving it.

We will see about keybinding settings in another section.

8. Animations in Hyprland

Setting cool animations for window opening, workspace switching is another way to make your Hyprland setup look cool.

To set animations, you need to get Bezier curve values. You can visit the site below to design your curve or select a preset one.

Bezier Curve Generator

Use the red dot to adjust the curve and see the transition using the button as shown in the screenshot below.

Once set, you will get 4 sets of values in the form 0.19, 1, 0.52, 0.35. Note this value.

Now, in Hyprland config, go to the LOOK AND FEEL section, scroll down to the animation part.

Here, set the bezier transition value like:

# bezier = Name_for_your_bezier, value_you_copied
bezier = customBezier, 0.19, 1, 0.52, 0.35

Now that you have defined the animation transition, set it to the section you needed, like window opening (windows), closing (windowsOut), etc. Here, I have set this animation to workspace switching:

# animation = windows, ON/OFF, Speed, Bezier_name
animation = workspaces, 1, 6, customBezier

Please refer to the animation wiki for detailed settings.

9. Variables in Hyprland

Hyprland uses variables for controlling several aspects of the system.

Here, I will show you a couple of variable settings so that you can use other variables pretty easily.

First, visit the Hyprland Variables Wiki page.

Hyprland Variables Wiki

There, you can find columns of variable names and their expected types, like Boolean, Integer, etc. It is divided into various categories and sub-categories. To define a variable, you have to open a category in curly braces.

Let’s say, I want to set an option to resize the window by dragging from the border in tiled mode. So, I have an option called resize_on_border that comes under general section. To define it,

general {
    resize_on_border = true
}

That’s it.

🚧

Most of the categories (eg. general) are already used in the default Hyprland config. So, instead of blindly defining a category like general, first check if that category is already present. If present, define the variable inside that category section only.

If any section has a subcategory, use it like nested. For example, the general category has a subcategory called snap, we will define it using:

general {
    general section variable definition.
    
    snap {
        subsection variable definition.
    }
}

Resize floating window

There can be some floating window in tile mode like app preferences, file choosers, etc. You can enable corner resize these floating window using the resize_corner variable in general section.

general {
    resize_corner = 3
}

Here, the value 3 implies drag and resize from bottom-right corner.

Value	Corner to Drag
1	Top-left
2	Top-right
3	Bottom-right
4	Bottom-left
0	Disable resize corner

Customizing the decorations

The decorations section is where options for opacity, blur, etc. are present. Therefore, if you check the default Hyprland config, you can see some values are preset in these sections. Here are some of my thoughts.

You can change the active_opacity to values like 0.8 to make active windows a bit transparent. Don’t forget to change inactive_opacity as well.
Blur can be make more cool by increasing the passes count, but this will have strain on the GPU.
It is recommended to turn on new_optimizations to improve performance.

Workspace and touchpad

Hyprland supports swipe to change workspace gesture. This is disabled by default. So, you need to set it true.

gestures {
    workspace_swipe = true
    workspace_swipe_fingers = 3
    
}

Set custom variables

Like any other programming language, Hyprland also supports assigning values to random custom variables created by you.

For example, if you want to set the value of a variable myLauncher to point to a command to open Wofi launcher, use the format:

$myLauncher = wofi --show drun

Now, you can use this variable name instead of the whole command every time it is needed. This is especially useful if you want to define default apps to some categories.

It is shown clearly in the default config of Hyprland, where variable terminal is assigned to Kitty terminal and filemanager is assigned to Dolphin file manager.

Similarly, you can define:

$myPersonalBrowser = firefox
$myKeyboardBrowser = nyxt

10. Environment variables in Hyprland

Several settings for Hyprland depends on environment variables, like cursor themes, QT and Wayland-specific configurations, etc.

To define an environment variable, you need to use the env keyword. Usual format is:

env = ENVIRONMENT_VARIABLE_NAME, VALUE

For example, in order to work some QT applications in Wayland and fallback to x11 if not available, we use the QT_QPA_PLATFORM environment variable.

env = QT_QPA_PLATFORM,wayland;xcb

🚧

Never put double quotes around the value.

11. Set Hyprcursor

Hyprcursor is a space-efficient cursor set available for Hyprland. Here, we will see how to set rose-pine-hyprcursor theme in Hyprland. First, install it from AUR.

yay -S rose-pine-hyprcursor

Once installed, open the Hyprland config and set the HYPRCURSOR_THEME environment variable.

env = HYPRCURSOR_THEME,rose-pine-hyprcursor

Similarly, you can check the cursor for the current session only using the hyprctl command:

hyprctl setcursor rose-pine-hyprcursor 24

📋

Here, 24 is the cursor size.

12. Set keyboard shortcuts

How can we use a tiling window compositor without having custom screenshots?

Hyprland has a super easy method to set custom keybindings. Let’s take a look.

In the default configuration, you can find a dedicated KEYBINDINGS section. For beginners, it is recommended to define keybindings under this section.

To define a keybinding, we use the keyword bind with the following syntax:

bind = MODIFIER_KEY,REQUIRED_KEY,DISPATCHERS, PARAMETERS

For example, let’s say we want to open Nautilus file manager using the command SUPER+O.

So, we will use the format:

bind = SUPER,O,exec,nautilus

Now, here the dispatcher used is exec, used to run a shell command. You can see more dispatchers supported by Hyprland in the detailed Wiki.

You can set the SUPER key to a variable, if you want to make the code clean:

$mainMod = SUPER

Bonus: Autostart Apps

Sometimes, it is necessary to autostart some apps. We have seen setting apps autostart in some earlier part of this article.

Hyprland uses exec-once command to autostart the app at login time. So, if you want an app to autostart, use:

# exec-once NAME_OF_APP

Here is how we start Hyprpaper and Waybar at the login time:

exec-once hyprpaper & waybar

Conclusion

As I said in the beginning, there is no end to how much you can customize Hyprland. The wiki is extensive and you can dig it in for more detailed information.

I wanted to give you a starting point for Hyprland configuration and customization. I do hope that you find it useful in enhancing your Hyprland experience.

Blog