Getting Wallpapers Right With Hyprpaper in Hyprland

A beautiful wallpaper enhances the aesthetic appeal of a desktop.

In desktop environments like GNOME and KDE, all you have to do is a right-click to set wallpaper.

However, that's not how we roll in the Hyprland. We do all sort of configuration to make it work.

But that's the fun of it, right? Let's see how to utilize Hyprpaper in Hyprland for your wallpaper setup.

What is Hyprpaper?

Hyprpaper is a Wayland wallpaper utility, which works on Hyprland and other wlroots-based compositors. This means that you can use this in other desktops like Sway, even though it is a Hyprland program.

Let's take a look at some of its features.

• Per-output wallpapers
• Fill, tile or contain modes
• Fractional scaling support
• IPC for blazing fast wallpaper switches

Install Hyprpaper on your Linux distribution

Since Hyprpaper is an important part of Hyprland, it should be present in the default repositories of distributions that have Hyprland present.

In Arch Linux, you can install Hyprpaper using the command:

sudo pacman -S hyprpaper

Fedora users can use:

sudo dnf install hyprpaper

openSUSE users can install it using the zypper package manager:

sudo zypper install hyprpaper

Using Hyprpaper

Unlike usual wallpaper managers, Hyprpaper does not have a GUI. This should not surprise you, as you are in Hyprland now.

Here, you need to tweak the configuration file of Hyprpaper for necessary changes.

Simple Hyprpaper configuration

A basic configuration of Hyprpaper should contain the following two lines:

wallpaper {
    monitor =  DP-1
    path = /home/itsfoss/Pictures/Wallpapers/itsfoss-wallpaper.png
}

To set wallpaper for multiple monitors, use separate wallpaper {} blocks with the monitor names.

Wait, how to get monitor name?

In the above section, you need the name of the monitors to set wallpaper to that particular monitor.

On Hyprland, you can use the command below to get the name of your monitor/monitors.

hyprctl monitors

From the above screenshot, the monitor name is Virtual-1 as this is a Virtual machine. Your name can be HDMI-1, DP-1 etc.

Make Wallpaper Slideshow

If you have a collection of wallpapers in a folder, you can make Hyprpaper change wallpaper at specfic interval from these folder.

To do this, replace the value of the path option to a folder instead of a particular file.

wallpaper {
    monitor = Virtual-1
    path = /home/itsfoss/Pictures/Wallpapers/
    timeout = 60
}

Now, by default, Hyprpaper changes the wallpaper every 30 seconds. To set a custom timeout, use the timeout option. It's value is in seconds. So, according to above example, the wallpapers from the /home/itsfoss/Pictures/Wallpapers/ directory will be changed every 60 seconds.

Add the splash text

You can add a splash text over the wallpaper using the splash option.

Open the Hyprpaper config file and add the line at the end:

splash = true

Now, when you reload the Hyprpaper, you will get a splash text displayed/hidden as per your choice.

Other than that, you can adjust the spacing of this text by using the splash_offset variable. The value is relative to the bottom.

You can change the transparency of the splash text using splash_opacity variable.

splash = true
splash_offset = 50.0
splash_opacity = 0.7

Switch wallpaper with shortcuts

Until now, you must have observed that for each wallpaper change, you need to restart Hyprpaper to get the effect. However, Hyprpaper utilizes IPC or Inter-Process Communication to switch between wallpapers quickly and without reloading the entire program each time a wallpaper is changed.

Here, we will use the hyprctl command of Hyprland to manage the Hyprpaper wallpapers.

The general syntax to change wallpaper is:

hyprctl hyprpaper wallpaper "[monitor], [path], [fit_mode]"

But before that, open your Hyprland config:

vim .config/hypr/hyprland.conf

Now, let's say you have stored the images as 1.png to 5.png in the ~/Pictures/Wallpapers directory.

So, for each wallpaper, create a variable. This is not necessary, and we are doing it for convenience with the keyboard shortcuts.

$wall_1 = hyprctl hyprpaper wallpaper "Virtual-1,~/Pictures/Wallpapers/1.png,tile"

$wall_2 = hyprctl hyprpaper wallpaper "Virtual-1,~/Pictures/Wallpapers/2.png,fill"

$wall_3 = hyprctl hyprpaper wallpaper "Virtual-1,~/Pictures/Wallpapers/3.png,contain"

$wall_4 = hyprctl hyprpaper wallpaper "Virtual-1,~/Pictures/Wallpapers/4.png"

$wall_5 = hyprctl hyprpaper wallpaper "Virtual-1,~/Pictures/Wallpapers/5.png"

To assign a keyboard shortcut, the general syntax in Hyprland is:

bind = modifier_key,desired_key,action,value

Look at the sample Hyprland key bind config shown below:

bind = $mainMod, H, exec, $wall_1
bind = $mainMod, J, exec, $wall_2
bind = $mainMod, K, exec, $wall_3
bind = $mainMod, B, exec, $wall_4
bind = $mainMod, N, exec, $wall_5

Shortcuts like Super + H are assigned to the respective wallpaper change command. The result will be, when you press that shortcut, the related wallpaper will be loaded.

Random wallpapers for different workspaces

If you want to get a random wallpaper for workspace switch, we need to create a custom script called change_wallpapers.sh inside ~/.config/hypr/ directory.

#!/bin/bash

WALLPAPER_DIRECTORY=~/Pictures/Wallpapers

WALLPAPER=$(find "$WALLPAPER_DIRECTORY" -type f | shuf -n 1)

hyprctl hyprpaper wallpaper "Virtual-1,$WALLPAPER,fill"

Once the script is ready, give the script execution permission.

chmod +x change_wallpapers.sh

After that, open the Hyprland config and add a key binding to change the wallpaper at random.

bind = $mainMod, 1, exec, ~/.config/hypr/change_wallpapers.sh
bind = $mainMod, 2, exec, ~/.config/hypr/change_wallpapers.sh
bind = $mainMod, 3, exec, ~/.config/hypr/change_wallpapers.sh
bind = $mainMod, 4, exec, ~/.config/hypr/change_wallpapers.sh
bind = $mainMod, 5, exec, ~/.config/hypr/change_wallpapers.sh

You can see that we have assigned SUPER + 1 through SUPER + 5 to change wallpaper. This is mandatory. Becuase SUPER + <number> is the shortcut used to switch workspaces. We are assigning the changing wallpaper action the same shortcut as changing workspaces, so that when the workspace change action is called, the associated wallpaper change also called.

Since this works by setting keyboard shortcuts, wallpaper won't be changed if we switch workspace using other methods like panel buttons. For that, you need to configure the respective panel.

Set day-night wallpapers

Now, it's time to set wallpapers according to day and night timing. Here, we use the cron job concepts.

First, you need to create a script, called day_night.sh. You can create this inside the ~/.config/hypr/ folder for easy access.

Inside this file, add these lines:

#!/bin/bash

# Wait for 5 seconds to start the script.
sleep 5

# Define daytime and nighttime image to respective variables
DAYTIME_WALLPAPER=~/Pictures/Wallpapers/3.png
NIGHTTIME_WALLPAPER=~/Pictures/Wallpapers/4.png

# Calculate the present hour and save it to a variable 
PRESENT_TIME=$(date +%H)

# In an if loop, check if current time is between 6 am and 6 pm 
# and assign day wallpaper to wallpaper variable.
# Else, if time is between 6 pm and 6 am, 
# assign night time wallpaper to wallpaper variable.
if [ $PRESENT_TIME -ge 6 ] && [ $PRESENT_TIME -lt 18 ]; then
	WALLPAPER=$DAYTIME_WALLPAPER
else
	WALLPAPER=$NIGHTTIME_WALLPAPER
fi

# Sleep 5 secconds to make sure that everything has time.
sleep 5

# Apply the wallpaper to current display.
hyprctl hyprpaper wallpaper "Virtual-1,$WALLPAPER,fill"

# Sleep for a second
sleep 1

# Exit with success.
exit 0

This simple bash script, saved as day_night.sh, checks the current hour. If it is greater than 6 and less than 18 (6 PM), a pre-defined daytime wallpaper is applied. In other case, a night wallpaper is applied. Don't forget to make it executable!

Now, we don't need this script to run all the time. So, using cron, we will set this to run exactly at 6 and 18 hours.

On a terminal. Run the command:

crontab -e

Here, in the editor, enter the lines as below:

0 6 * * * /home/itsfoss/.config/hypr/day_night.sh
0 18 * * * /home/itsfoss/.config/hypr/day_night.sh

Save and exit. You can use crontab -l to check whether our job is running.

Now, if you restart the system, there is a chance that you end up with no wallpaper. To avoid that, you can autostart your script at Hyprland startup.

Add these line in your Hyprland config:

exec-once hyprpaper
exec-once /home/team/.config/hypr/day_night.sh

That's it. Enjoy your day/night wallpapers!

Conclusion

This much trouble for something as simple as wallpapers? Well, things are vastly different in the Hyprland and to the enthusiasts, this is the fun part. Doing things in a complicated manner teaches things you probably would not have learned on your own.

On a similar note, you might want to learn about configuring the nightlight feature in Hyprland.

Using Nightlight in Hyprland

Let there be (night) light in the hyprland.

It's FOSSSreenath

Do let me know if you have questions or suggestions on this topic.