> ## Content Index > Fetch the complete content index at: https://itsfoss.com/llms.txt > Use this file to discover other available public pages before exploring further. # Getting Wallpapers Right With Hyprpaper in Hyprland - URL: https://itsfoss.com/hyprpaper-hyprland/ - Published: 2024-12-06T17:57:08.000Z - Updated: 2026-03-24T09:41:22.000Z - Description: Time to customize the looks of your Hyprland desktop with wallpapers. Hyprpaper is your friend here. - Author: Sreenath - Tags: 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](https://github.com/hyprwm/hyprpaper?ref=itsfoss.com) 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: ```bash sudo pacman -S hyprpaper ``` Fedora users can use: ```bash sudo dnf install hyprpaper ``` openSUSE users can install it using the zypper package manager: ```bash sudo zypper install hyprpaper ``` 🚧 For other distributions, you may need to [build it from source code](https://itsfoss.com/install-software-from-source-code/) manually. In that case, keep an eye on the dependencies. ## Using Hyprpaper Unlike [usual wallpaper managers](https://itsfoss.com/applications-manage-wallpapers-ubuntu/), 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. 🚧 Hyprpaper expects its configuration file at `.config/hypr/hyprpaper.conf`. You need to create this file to configure the program. ## Simple Hyprpaper configuration A basic configuration of Hyprpaper should contain the following two lines: ```hyprlang 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. 📋 Replace the monitor name and image path with your specific values. ![A screenshot showing wallpaepr set to two monitors in Hyprland using Hyprpaper wallpaper utility.](https://itsfoss.com/content/images/2026/03/hyprland-hyprpaper-different-wallpaper-for-different-monitor.jpg) Dual monitor, different wallpapers ## 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. ```hyprlang hyprctl monitors ``` ![screenshot showing the hyprctl monitors command and highlighting the monitor name. It is Virtual-1 in this case, since it is a Virtual Machine screen.](https://itsfoss.com/content/images/2026/03/get-the-monitor-name-1.png) Get Monitor Name 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. ```hyprlang 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: ```hyprlang splash = true ``` 🚧 The `splash` should be outside the `wallpapers {}` block. Now, when you reload the Hyprpaper, you will get a splash text displayed/hidden as per your choice. ![Hyprpaper displaying a splash text on top of the wallpaper.](https://itsfoss.com/content/images/2026/03/splash-text-in-hyprpaper.png) Splash Text 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. ```hyprlang splash = true splash_offset = 50.0 splash_opacity = 0.7 ``` 📋 From what I checked, the splash text was not editable. Please correct me if I am wrong in the comments. ## 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. 💡 This is possible since Hyprpaper supports IPC (Inter-Process Communication) by default. The general syntax to change wallpaper is: ``` hyprctl hyprpaper wallpaper "[monitor], [path], [fit_mode]" ``` 🚧 If you are using hyprpaper inside a script, use double quotes for `"monitor,path,fit_mode"`. Because, single quotes will not expand variables in case you are providing path as a variable. 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. ```hyprlang $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" ``` 💡 In the above code, we didn't set the `fit_mode` for all items. This is because `fit_mode` is optional and by default take the value `cover`. To assign a keyboard shortcut, the general syntax in Hyprland is: ```hyprlang bind = modifier_key,desired_key,action,value ``` Look at the sample Hyprland key bind config shown below: ```hyprlang 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 ``` 💡 The `$mainMod` by default, denotes the SUPER key in Hyprland. If you want to assign SUPER+SHIFT, use `$mainMod SHIFT`. More details are discussed in our [Hyprland customization guide](https://itsfoss.com/configuring-hyprland/). 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. Showing wallpaper change using shortcuts. 🚧 If changing wallpaper not working for you, try to delete the `wallpaper {}` block in `~/.config/hypr/hyprpaper.conf` and reload Hyprpaper using `pkill hyprpaper && hyprpaper & disown`. Now, try to change wallpaper. ## 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. ```bash #!/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. ```bash chmod +x change_wallpapers.sh ``` After that, open the Hyprland config and add a key binding to change the wallpaper at random. ```hyprlang 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 + ` 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. Random wallpaper per workspace 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](https://itsfoss.com/cron-job/). 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: ```bash #!/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: ```bash crontab -e ``` Here, in the editor, enter the lines as below: ```bash 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: ```hyprlang 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](https://itsfoss.com/nightlight-hyprland/). [Using Nightlight in HyprlandLet there be (night) light in the hyprland.![](https://itsfoss.com/content/images/icon/android-chrome-512x512-306.png)It's FOSSSreenath![](https://itsfoss.com/content/images/thumbnail/nightlight-in-hyprland-3.png)](https://itsfoss.com/nightlight-hyprland/) Do let me know if you have questions or suggestions on this topic.