Linux Rofi Wallpaper Engine

Rofi-based wallpaper selector for Linux, working with wallpapers downloaded through Wallpaper Engine (Steam) and rendered by Almamu/linux-wallpaperengine.

Steam Workshop → subscribe to wallpaper → file downloads locally
      ↓
wallpapers.conf (1 Workshop URL per line)
      ↓
SUPER + W → Rofi displays thumbnails → select → wallpaper changes immediately

The script is not tied to any specific compositor. Integration examples are provided for Hyprland and Niri. Other Wayland compositors should work as well; adjust the autostart and keybind sections as needed.

Features

• Use Workshop URLs directly; no need to enter IDs manually
• Thumbnail previews in Rofi (preview.jpg/.jpeg/.png/.webp/.gif)
• Duplicate Workshop IDs are skipped automatically
• The last selected wallpaper is saved automatically and restored at login
• Wallpaper audio is muted automatically (--silent)
• Workshop video files are not stored in this repository

Requirements

• Linux + Wayland compositor (Hyprland, Niri, etc.)
• Wallpaper Engine on Steam, with at least one subscribed Workshop wallpaper
• linux-wallpaperengine
• Rofi
• Bash

Install on Arch Linux

paru -S linux-wallpaperengine-git
sudo pacman -S rofi-wayland

Installation

git clone https://github.com/ilhamfirmansyahhub/linux-wallpaper-engine.git
cd linux-wallpaper-engine

mkdir -p ~/.local/bin ~/.config/wallpaperengine
cp wallpaper-engine-select wallpaper-engine-start ~/.local/bin/
chmod +x ~/.local/bin/wallpaper-engine-select ~/.local/bin/wallpaper-engine-start

cp wallpapers.conf ~/.config/wallpaperengine/wallpapers.conf
$EDITOR ~/.config/wallpaperengine/wallpapers.conf

Adding Wallpapers

Add one Workshop URL per line in wallpapers.conf:

https://steamcommunity.com/sharedfiles/filedetails/?id=2458916637
https://steamcommunity.com/sharedfiles/filedetails/?id=3727360247

Make sure the wallpaper has been subscribed to and fully downloaded by Steam. Otherwise, it will not appear in Rofi.

Usage

• Select a wallpaper: ~/.local/bin/wallpaper-engine-select (or the SUPER + W shortcut)
• Restore the last wallpaper at login: ~/.local/bin/wallpaper-engine-start

The selection is saved in ~/.config/wallpaperengine/current. If no wallpaper has been selected yet, it falls back to ID 2458916637 (which can be changed in wallpaper-engine-start).

Changing the Monitor Name

The scripts use eDP-1 by default (common on laptops). Check your monitor name:

# Hyprland
hyprctl monitors

# Niri
niri msg outputs

If it differs, replace --screen-root eDP-1 in wallpaper-engine-select and wallpaper-engine-start with your monitor name (for example, DP-1, DP-4, or HDMI-A-1).

Hyprland Integration

Example files are available at hyprland/startup.lua.example and hyprland/keybinds.lua.example.

Add the following to your Hyprland configuration:

hl.exec_cmd("~/.local/bin/wallpaper-engine-start")
hl.bind("SUPER + W", hl.dsp.exec_cmd("~/.local/bin/wallpaper-engine-select"))

(The syntax depends on the Hyprland Lua configuration API you use.)

Niri Integration

Niri uses KDL configuration (~/.config/niri/config.kdl).

Autostart - add this to the spawn-at-startup section:

spawn-at-startup "bash" "-c" "~/.local/bin/wallpaper-engine-start"

Keybind - add this to the binds { } block:

binds {
    Mod+W { spawn "bash" "-c" "~/.local/bin/wallpaper-engine-select"; }
}

Reload the configuration (niri msg action load-config or restart the session), then test Mod+W.

Multi-monitor

If you have more than one display, the scripts need to be adjusted to run a wallpaper on each output (loop over --screen-root for each monitor).

Troubleshooting

Problem	Solution
Wallpaper does not appear in Rofi	Check ls ~/.local/share/Steam/steamapps/workshop/content/431960 and make sure the ID folder exists and contains a preview.* file
Works manually but not automatically at login	Test ~/.local/bin/wallpaper-engine-start manually first. If it works, the issue is with compositor autostart integration, not the renderer
Wrong monitor	Check the output name again (hyprctl monitors / niri msg outputs) and update --screen-root in both scripts
Steam uses another library	Edit the STEAM_WORKSHOP variable in wallpaper-engine-select

Repository Contents

linux-wallpaper-engine/
├── wallpaper-engine-select
├── wallpaper-engine-start
├── wallpapers.conf
├── hyprland/
│   ├── startup.lua.example
│   └── keybinds.lua.example
├── .gitignore
└── README.md

This repository only contains scripts and example configuration. Do not commit Workshop-downloaded wallpaper videos/GIFs.

Credits

• Linux renderer: Almamu/linux-wallpaperengine
• Wallpaper source: Wallpaper Engine (Steam)
• Menu/selector: Rofi