<img src="https://github.com/Almamu/linux-wallpaperengine/raw/v0.0.1/docs/images/logo-light.svg" alt="Linux Wallpaper Engine" width="80%">









<small>Tux image based on original Tux by Larry Erwing, The GIMP</small>







<a href="https://github.com/Almamu/linux-wallpaperengine/blob/main/LICENSE"><img src="https://img.shields.io/github/license/Almamu/linux-wallpaperengine" /></a>
<a href="https://github.com/Almamu/linux-wallpaperengine/actions?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/Almamu/linux-wallpaperengine/cmake.yml?branch=main" /></a>
<img src="https://img.shields.io/coderabbit/prs/github/Almamu/linux-wallpaperengine?utm_source=oss&utm_medium=github&utm_campaign=Almamu%2Flinux-wallpaperengine&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews" />
<a href="https://github.com/Almamu/linux-wallpaperengine/pulse"><img src="https://img.shields.io/endpoint?url=https://ghloc.vercel.app/api/Almamu/linux-wallpaperengine/badge?filter=.cpp$,.h$&style=flat&logoColor=white&label=Lines of Code" /></a>
<a href="https://www.codefactor.io/repository/github/almamu/linux-wallpaperengine"><img src="https://img.shields.io/codefactor/grade/github/Almamu/linux-wallpaperengine" /></a>
<a href="https://github.com/Almamu/linux-wallpaperengine/graphs/commit-activity"><img src="https://img.shields.io/github/commit-activity/m/Almamu/linux-wallpaperengine" /></a>
<a href="https://github.com/Almamu/linux-wallpaperengine/graphs/contributors"><img src="https://img.shields.io/github/contributors/Almamu/linux-wallpaperengine" /></a>
<a href="https://github.com/Almamu/linux-wallpaperengine/issues"><img src="https://img.shields.io/github/issues-raw/Almamu/linux-wallpaperengine" /></a>
<a href="https://github.com/Almamu/linux-wallpaperengine/issues?q=is%3Aissue+is%3Aopen+label%3A%22help%20wanted%22"><img src="https://img.shields.io/github/issues/Almamu/linux-wallpaperengine/help%20wanted?color=green" alt="help wanted"></a>
<a href="https://wpengine.alma.mu/"><img src="https://img.shields.io/badge/showcase_gallery-blue" alt="Showcase gallery" /></a>
<a href="https://deepwiki.com/Almamu/linux-wallpaperengine"><img src="https://img.shields.io/badge/Deepwiki-Almamu%2Flinux--wallpaperengine-blue?logo=data%3Aimage%2Fpng%3Bbase64%2CiVBORw0KGgoAAAANSUhEUgAAACwAAAAyCAYAAAAnWDnqAAAAAXNSR0IArs4c6QAAA05JREFUaEPtmUtyEzEQhtWTQyQLHNak2AB7ZnyXZMEjXMGeK%2FAIi%2BQuHrMnbChYY7MIh8g01fJoopFb0uhhEqqcbWTp06%2Fuv1saEDv4O3n3dV60RfP947Mm9%2FSQc0ICFQgzfc4CYZoTPAswgSJCCUJUnAAoRHOAUOcATwbmVLWdGoH%2F%2FPB8mnKqScAhsD0kYP3j%2FYt5LPQe2KvcXmGvRHcDnpxfL2zOYJ1mFwrryWTz0advv1Ut4CJgf5uhDuDj5eUcAUoahrdY%2F56ebRWeraTjMt%2F00Sh3UDtjgHtQNHwcRGOC98BJEAEymycmYcWwOprTgcB6VZ5JK5TAJ%2BfXGLBm3FDAmn6oPPjR4rKCAoJCal2eAiQp2x0vxTPB3ALO2CRkwmDy5WohzBDwSEFKRwPbknEggCPB%2FimwrycgxX2NzoMCHhPkDwqYMr9tRcP5qNrMZHkVnOjRMWwLCcr8ohBVb1OMjxLwGCvjTikrsBOiA6fNyCrm8V1rP93iVPpwaE%2BgO0SsWmPiXB%2Bjikdf6SizrT5qKasx5j8ABbHpFTx%2BvFXp9EnYQmLx02h1QTTrl6eDqxLnGjporxl3NL3agEvXdT0WmEost648sQOYAeJS9Q7bfUVoMGnjo4AZdUMQku50McDcMWcBPvr0SzbTAFDfvJqwLzgxwATnCgnp4wDl6Aa%2BAx283gghmj%2Bvj7feE2KBBRMW3FzOpLOADl0Isb5587h%2FU4gGvkt5v60Z1VLG8BhYjbzRwyQZemwAd6cCR5%2FXFWLYZRIMpX39AR0tjaGGiGzLVyhse5C9RKC6ai42ppWPKiBagOvaYk8lO7DajerabOZP46Lby5wKjw1HCRx7p9sVMOWGzb%2FvA1hwiWc6jm3MvQDTogQkiqIhJV0nBQBTU%2B3okKCFDy9WwferkHjtxib7t3xIUQtHxnIwtx4mpg26%2FHfwVNVDb4oI9RHmx5WGelRVlrtiw43zboCLaxv46AZeB3IlTkwouebTr1y2NjSpHz68WNFjHvupy3q8TFn3Hos2IAk4Ju5dCo8B3wP7VPr%2FFGaKiG%2BT%2Bv%2BTQqIrOqMTL1VdWV1DdmcbO8KXBz6esmYWYKPwDL5b5FA1a0hwapHiom0r%2FcKaoqr%2B27%2FXcrS5UwSMbQAAAABJRU5ErkJggg%3D%3D" alt="DeepWiki documentation" /></a>

🖼️ Linux Wallpaper Engine

Bring Wallpaper Engine-style live wallpapers to Linux! This project allows you to run animated wallpapers from Steam’s Wallpaper Engine right on your desktop.

---

📦 System Requirements

To compile and run this, you'll need:

• WallpaperEngine installed in Steam (or WallpaperEngine assets somewhere in your system)
• OpenGL 3.3 support
• CMake
• LZ4, Zlib
• SDL2
• FFmpeg
• X11 or Wayland
• Xrandr (for X11)
• GLFW3, GLEW, GLUT, GLM
• MPV
• PulseAudio
• FFTW3

Ubuntu 22.04

sudo apt-get update
sudo apt-get install build-essential cmake libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl-dev libglew-dev freeglut3-dev libsdl2-dev liblz4-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libxxf86vm-dev libglm-dev libglfw3-dev libmpv-dev mpv libmpv1 libpulse-dev libpulse0 libfftw3-dev

Ubuntu 24.04

sudo apt-get update
sudo apt-get install build-essential cmake libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl-dev libglew-dev freeglut3-dev libsdl2-dev liblz4-dev libavcodec-dev libavformat-dev libavutil-dev libswscale-dev libxxf86vm-dev libglm-dev libglfw3-dev libmpv-dev mpv libmpv2 libpulse-dev libpulse0 libfftw3-dev

Alt linux

sudo epm update
sudo epm install gcc-c++ make cmake libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel libGL-devel libGLEW-devel freeglut-devel libSDL2-devel liblz4-devel libavcodec-devel libavformat-devel libavutil-devel libswscale-devel libXxf86vm-devel libglm-devel libglfw3-devel libmpv-devel mpv libpulseaudio-devel libpulseaudio libfftw3-devel libpng-devel libffi-devel libswresample-devel libgmpxx-devel

Fedora 42

sudo dnf update
sudo dnf install gcc g++ cmake libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel mesa-libGL-devel glew-devel freeglut-devel SDL2-devel lz4-devel ffmpeg ffmpeg-free-devel libXxf86vm-devel glm-devel glfw-devel mpv mpv-devel pulseaudio-libs-devel fftw-devel gmp-devel

Arch Linux

Arch Linux users can install linux-wallpaperengine-git from the AUR:

yay -S linux-wallpaperengine-git

---

🚀 Getting Started

1. Get Wallpaper Engine Assets

You must own and install Wallpaper Engine via Steam. This provides the required assets used by many backgrounds.

Right now the application will automatically detect everything for you as long as the official Wallpaper Engine is installed through Steam.

The app will look for the Steam installation in the following locations:

~/.steam/steam/
~/.local/share/Steam/
~/.var/app/com.valvesoftware.Steam/.local/share/Steam/
~/snap/steam/common/.local/share/Steam/

---

❗ If Assets Aren’t Found Automatically

If the assets are not detected automatically, you'll see a message like this:

Cannot find a valid assets folder, resolved to 'assets'

You can copy the assets folder manually:

1. In Steam, right-click Wallpaper Engine → Manage → Browse local files
2. Copy the assets folder
3. Paste it into a new folder somewhere in your system
4. Run the app with the --assets-dir option pointing to the new folder:

linux-wallpaperengine --assets-dir /path/to/assets

---

2. Build from Source

⚠️ If you installed the AUR package mentioned before, you can skip this step.

Clone the repo:

git clone --recurse-submodules https://github.com/Almamu/linux-wallpaperengine.git
cd linux-wallpaperengine

Build it:

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE='Release' -DCMAKE_INSTALL_PREFIX="/usr" -DWPBUILD_FRONTEND=ON ..
make install

This will install the linux-wallpaperengine binary in /usr/bin and the linux-wallpaperengine-core library in /usr/lib for other frontends and applications to use.

---

🧪 Usage

Basic syntax:

linux-wallpaperengine [options] <default background_id or path>

You can use either: - A Steam Workshop ID (e.g. 1845706469) - A path to a background folder

---

What about a GUI?

Implementing a GUI is out of scope for now. There's a few developers that decided to focus on this and created their own. If you're one of those developers, feel free to open an issue to get your project included here!

• simple-linux-wallpaperengine-gui by @Maxnights
• linux-wallpaper-engine by @jagrat7
• wallpaperengine-gui by @MikiDevLog
• linux-wallpaperengine-controllfer for Noctalia Shell by @PaloMiku
• waypaper by @anufrievroman

🔧 Common Options

Option	Description
--silent	Mute background audio
--volume <val>	Set audio volume
--noautomute	Don't mute when other apps play audio
--no-audio-processing	Disable audio reactive features
--fps <val>	Limit frame rate
--window <XxYxWxH>	Run in windowed mode with custom size/position
--screen-root <screen>	Set as background for specific screen
--screen-span <screen-1>,<screen-2>,...	Stretch a single wallpaper across multiple screens
--bg <id/path>	Assign a background to a specific screen (use after --screen-root/--screen-span)
--scaling <mode>	Wallpaper scaling: stretch, fit, fill, or default
--clamping <mode>	Set texture clamping: clamp, border, repeat
--assets-dir <path>	Set custom path for assets
--screenshot <file>	Save screenshot (PNG, JPEG, BMP)
--list-properties	Show customizable properties of a wallpaper
--set-property name=value	Override a specific property
--disable-mouse	Disable mouse interaction
--disable-parallax	Disable parallax effect on backgrounds that support it
--no-fullscreen-pause	Prevent pausing while fullscreen apps are running
--fullscreen-pause-only-active	Wayland only: pause only when a fullscreen window is active
--fullscreen-pause-ignore-appid <val>	Wayland only: ignore fullscreen windows whose app_id contains <val> (repeatable)
--steam-dir <path>	Set custom path for Steam installation
--help	Show help
--version	Show version
---

💡 Examples

Run a background on a window

linux-wallpaperengine 1845706469

Run a background on HDMI-1 screen

linux-wallpaperengine --screen-root HDMI-1 --bg 1845706469

Run a background on a specific screen and a different one on the rest

linux-wallpaperengine --screen-root eDP-1 --bg 1845706469 2667198602

Run a background from a folder

linux-wallpaperengine ~/backgrounds/1845706469/

Assign backgrounds to screens with scaling

linux-wallpaperengine \
  --scaling stretch --screen-root eDP-1 --bg 2667198601 \
  --scaling fill --screen-root HDMI-1 --bg 2667198602

Stretch one wallpaper across multiple monitors

linux-wallpaperengine \
  --scaling fill --screen-span HDMI-A-1,DP-2,DP-3 --bg 1845706469

Run in a window

linux-wallpaperengine --window 0x0x1280x720 1845706469

Limit FPS to save power

linux-wallpaperengine --fps 30 1845706469

Take a screenshot

linux-wallpaperengine --screenshot ~/wallpaper.png 1845706469

This can be useful as output for pywal or other color systems that use images as a basis to generate a set of colors to apply to your system.

View and change properties

linux-wallpaperengine --list-properties 2370927443

The output includes all the relevant information for each of the different properties:

barcount - slider
    Description: Bar Count
    Value: 64
    Minimum value: 16
    Maximum value: 64
    Step: 1

bloom - boolean
    Description: Bloom
    Value: 0
frequency - combolist
    Description: Frequency
    Value: 2
        Posible values:
        16 -> 1
        32 -> 2
        64 -> 3

owl - boolean
    Description: Owl
    Value: 0
rain - boolean
    Description: Rain
    Value: 1
schemecolor - color
    Description: ui_browse_properties_scheme_color
    R: 0.14902 G: 0.23137 B: 0.4 A: 1
visualizer - boolean
    Description: <hr>Add Visualizer<hr>
    Value: 1
visualizercolor - color
    Description: Bar Color
    R: 0.12549 G: 0.215686 B: 0.352941 A: 1
visualizeropacity - slider
    Description: Bar Opacity
    Value: 1
    Minimum value: 0
    Maximum value: 1
    Step: 0.1

visualizerwidth - slider
    Description: Bar Spacing
    Value: 0.25
    Minimum value: 0
    Maximum value: 0.5
    Step: 0.01

Any of these values can be modified with the --set-property switch. Say you want to enable the bloom in this background, you would do so like this:

linux-wallpaperengine --set-property bloom=1 2370927443

---

🧪 Wayland & X11 support

For GNOME, KDE, Sway, Hyprland, Cinnamon, i3, etc... check the compatibility docs here.

---

🌈 Example Backgrounds

Want to see more examples of backgrounds that work? Head over to the project's website

---

🛠️ Development

If you're interested in contributing or building the project for development purposes, please refer to our Development Guide.

---

🙏 Special Thanks

• RePKG – for texture flag insights
• RenderDoc – the best OpenGL debugger out there!
• All the contributors that have created PR!