Skip to main content
This dotfiles setup includes wallpaper management through hyprpaper, a fast wallpaper daemon for Hyprland, along with a curated collection of wallpapers.

​
Overview

Hyprpaper is a lightweight wallpaper utility designed specifically for Hyprland that provides:
  • Fast wallpaper rendering
  • Multi-monitor support
  • Automatic wallpaper loading on startup
  • Low resource usage

​
Hyprpaper setup

​
Autostart configuration

Hyprpaper is configured to start automatically with Hyprland:
.config/hypr/hyprland.conf
exec-once = agsv1 & hyprpaper
Hyprpaper loads in the background when Hyprland starts, applying your configured wallpaper immediately.

​
Configuration

Create a configuration file at ~/.config/hypr/hyprpaper.conf:
~/.config/hypr/hyprpaper.conf
# Preload wallpapers
preload = ~/dotfiles/Wallpaper/wall-01.png
preload = ~/dotfiles/Wallpaper/cafe-at-night_00_3840x2160.png

# Set wallpaper for monitors
wallpaper = ,~/dotfiles/Wallpaper/wall-01.png

# Disable splash text
splash = false

# Disable IPC
ipc = off

​
Configuration options

Preload wallpapers into memory for instant switching:
preload = /path/to/wallpaper.png
You can preload multiple wallpapers.
Set wallpaper for a specific monitor:
wallpaper = MONITOR,/path/to/wallpaper.png
Use , (empty) to apply to all monitors:
wallpaper = ,/path/to/wallpaper.png
Enable or disable splash text:
splash = true   # Show splash
splash = false  # Hide splash
Enable IPC for runtime control:
ipc = on   # Enable IPC
ipc = off  # Disable IPC

​
Multi-monitor configuration

For multiple monitors with different wallpapers:
~/.config/hypr/hyprpaper.conf
# Preload all wallpapers
preload = ~/dotfiles/Wallpaper/wall-01.png
preload = ~/dotfiles/Wallpaper/cafe-at-night_00_3840x2160.png
preload = ~/dotfiles/Wallpaper/samurai_strike.jpg

# Set per-monitor wallpapers
wallpaper = DP-1,~/dotfiles/Wallpaper/wall-01.png
wallpaper = DP-2,~/dotfiles/Wallpaper/cafe-at-night_00_3840x2160.png
wallpaper = HDMI-A-1,~/dotfiles/Wallpaper/samurai_strike.jpg
Use hyprctl monitors to see your monitor names (DP-1, HDMI-A-1, etc.)

​
Wallpaper collection

The dotfiles include a curated collection of wallpapers in the Wallpaper/ directory:

wall-01.png

2.27 MB - High quality wallpaper

cafe-at-night_00_3840x2160.png

7.25 MB - 4K night scene

street-tn.png

372 KB - Tokyo Night street scene

a_street_with_buildings_and_signs.png

2.27 MB - Urban landscape

samurai_strike.jpg

1.72 MB - Samurai artwork

​
Wallpaper directory structure

~/dotfiles/Wallpaper/
├── wall-01.png (2.3 MB)
├── cafe-at-night_00_3840x2160.png (7.6 MB)
├── street-tn.png (381 KB)
├── a_street_with_buildings_and_signs.png (2.4 MB)
└── samurai_strike.jpg (1.8 MB)

​
Using wallpapers

​
Set a single wallpaper

preload = ~/dotfiles/Wallpaper/cafe-at-night_00_3840x2160.png
wallpaper = ,~/dotfiles/Wallpaper/cafe-at-night_00_3840x2160.png

​
Street scene for lock screen

The street-tn.png is used for the lock screen in Hyprland:
.config/hypr/hyprland.conf
bindl=SUPER,L,exec, swaylock -f -e -l -L -s fill -i ~/dotfiles/Wallpaper/street-tn.png

​
Wallpaper formats supported

Hyprpaper supports common image formats:
  • PNG (recommended for best quality)
  • JPG/JPEG (good for smaller file sizes)
  • WebP
  • BMP

​
Adding custom wallpapers

1

Add wallpaper to directory

Copy your wallpaper to the Wallpaper directory:
cp /path/to/your-wallpaper.png ~/dotfiles/Wallpaper/
2

Preload the wallpaper

Add to hyprpaper.conf:
preload = ~/dotfiles/Wallpaper/your-wallpaper.png
3

Set as active wallpaper

Configure wallpaper assignment:
wallpaper = ,~/dotfiles/Wallpaper/your-wallpaper.png
4

Reload hyprpaper

Restart hyprpaper to apply changes:
killall hyprpaper && hyprpaper &

​
Runtime wallpaper switching

​
With IPC enabled

Enable IPC in hyprpaper.conf: 
ipc = on
Then use hyprctl to change wallpapers: 
# Preload a new wallpaper
hyprctl hyprpaper preload "~/dotfiles/Wallpaper/samurai_strike.jpg"

# Set wallpaper
hyprctl hyprpaper wallpaper ",~/dotfiles/Wallpaper/samurai_strike.jpg"

# Unload unused wallpaper
hyprctl hyprpaper unload "~/dotfiles/Wallpaper/old-wallpaper.png"

​
Wallpaper switcher script

Create a script to cycle through wallpapers:
~/dotfiles/scripts/wallpaper-switcher.sh
#!/bin/bash

WALLPAPERS=(
    "$HOME/dotfiles/Wallpaper/wall-01.png"
    "$HOME/dotfiles/Wallpaper/cafe-at-night_00_3840x2160.png"
    "$HOME/dotfiles/Wallpaper/samurai_strike.jpg"
)

CURRENT=$(cat ~/.current-wallpaper 2>/dev/null || echo 0)
NEXT=$(( (CURRENT + 1) % ${#WALLPAPERS[@]} ))

hyprctl hyprpaper preload "${WALLPAPERS[$NEXT]}"
hyprctl hyprpaper wallpaper ",${WALLPAPERS[$NEXT]}"

echo $NEXT > ~/.current-wallpaper
notify-send "Wallpaper Changed" "Now using wallpaper $((NEXT + 1))/${#WALLPAPERS[@]}"
Make it executable and bind to a key: 
chmod +x ~/dotfiles/scripts/wallpaper-switcher.sh
.config/hypr/hyprland.conf
bind = $mainMod, W, exec, ~/dotfiles/scripts/wallpaper-switcher.sh

​
Optimizing wallpapers

​
For 4K displays

Use high-resolution images (3840x2160 or higher): 
cafe-at-night_00_3840x2160.png - Perfect for 4K

​
For 1080p displays

Resize large images to save memory: 
# Using ImageMagick
convert input.png -resize 1920x1080 output.png

# Using ffmpeg
ffmpeg -i input.png -vf scale=1920:1080 output.png

​
Reduce file size

Optimize PNG files: 
# Using optipng
optipng -o7 wallpaper.png

# Using pngquant
pngquant --quality=80-95 wallpaper.png

​
Wallpaper recommendations

Anime/Art

  • High contrast artwork
  • Tokyo Night themed
  • Samurai/Japanese aesthetic

Nature

  • Night scenes
  • City landscapes
  • Minimalist designs

Abstract

  • Geometric patterns
  • Gradient backgrounds
  • Dark themes

Photography

  • Urban photography
  • Street scenes
  • Architectural shots

​
Troubleshooting

Check that hyprpaper is running:
pgrep -a hyprpaper
If not running, start it:
hyprpaper &
Verify the path in hyprpaper.conf:
ls -lh ~/dotfiles/Wallpaper/
Ensure paths use absolute paths or proper ~ expansion.
Use wallpapers that match or exceed your monitor resolution:
# Check monitor resolution
hyprctl monitors | grep -A 5 Monitor
Reduce the number of preloaded wallpapers:
# Only preload what you need
preload = ~/dotfiles/Wallpaper/wall-01.png

​
Alternative wallpaper tools

hyprpaper

Native Hyprland support, fast, lightweight

swaybg

Sway/wlroots wallpaper tool, Wayland compatible

wpaperd

Wallpaper daemon with scheduling

​
Wallpaper sources

Find high-quality wallpapers:

Hyprland

Hyprpaper autostart configuration

Lock screen

Swaylock wallpaper setup

​
Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us