[!IMPORTANT] Skwd-wall v2 beta is here! Join us on Discord if you want to be part of the steering the direction of the beta, report bugs or just chat :)

Skwd-wall v2 is the most ambitious software I've ever written, and as such I am expecting at least one bug, maybe two. Please don't hesitate to create a GitHub issue for any issues you encounter or suggestions you may have.

Current known issues / WIP:

WIP: Wallpaper Engine inconsistencies / bugs in comparison to (the real) Wallpaper Engine. This part of the application is still Work in Progress and does not have perfect coverage yet. Please report any issues you may find with Wallpaper Engine scenes ❤️

WIP: Debian version

WIP: A wiki & better documentation. Skwd-wall is packed with tons of features, but almost nothing is explained in detail in writing.

A video is a thousand pictures - Sun Tzu (probably)

https://github.com/user-attachments/assets/46efe308-806d-466d-8834-3052134f00eb

What is Skwd-wall?

Something so beautiful and aesthetic yet so lightweight to run amazingly on a celeron

You have returned the hope I lost

- FutureKismo

i honestly loved v1. such an amazing piece of kit, and my machine didn't mind running it. but v2 is like going from "family sedan fast" to "ferrari fast"

- WanderingAstarael

Skwd-wall is a wallpaper manager for most Linux distros and WM:s that can show Wallpaper Engine scenes (and browse them too!), images and videos and does so much more performant than most wallpaper daemons out there.

We got all the features from changing the layout to right-to-left for languages read that way to letting you put videos in the Niri backdrop (paused unless you're looking, of course), and so much more - if you can think of it for a wallpaper manager chances are high Skwd-wall does it.

So what about that performance claim? Don't take my word for it, I come with charts!

What does it do besides apply wallpapers? well...

What does it work on?

Skwd-wall has intentional wide support and targets all major distributions, Desktop Environments and Wayland compositors. However it does not support GNOME or Linux Mint's Cinnamon (yet!).

Who is Skwd-wall not for?

If you're someone that can reasonably name all the wallpapers you have, they're all images and you have one monitor chances are high Skwd-wall is not for you.

But if you're an aspiring wallpaper collector, like the idea of a program that tries to solve every wallpaper and theming problem you might ever have or you're just curious about Skwd-wall you have come to the right place!

The long story short - Personal motivation and development practices

This is part of my personal shell Skwd that I have broken out into a standalone component because it was a popular request.

I develop Skwd-wall because I feel most wallpaper selectors are very boring traditional grids, lack filtering options that don't accomodate people like me who have thousands of wallpapers, because video wallpaper daemons were so-so to ??? on the performance side of things and most of all because it is fun!

Note that I use AI tooling in my development just like I do in my professional life, however most of the (non-test, ain't no way I'm writing the 1000+ unit, integration and e2e tests that Skwd-wall v2 has manually) code is mine including the stupid decisions.

Base wallpaper path

The default is a Wallpapers folder inside your desktop's Pictures directory, including localized names such as Imágenes. Existing ~/Pictures/Wallpapers libraries keep their location. You can choose another folder in settings; spaces and non-English names work, and settings open even before you add a wallpaper.

Download filters

In Settings > Sources, expand a source and enable Show Apply button to change several download filters before sending one search request. Press Apply, or press Enter in the search field, to search with all your changes. Each source has its own choice. The button is hidden by default, so each filter change searches immediately.

Expand Wallhaven or Steam Workshop to choose the default filters for each new browser session. Changes made while browsing last until the browser closes.

Compositor-specific examples on how to launch

Skwd-wall-v2 comes with a .desktop file so you can launch it through your launcher. But should you wish to keybind it, this is how you do that.

# Niri
Mod+T hotkey-overlay-title="Skwd-wall" { spawn "skwd-wall-v2"; }

# Hyprland
hl.bind("SUPER + W", hl.dsp.exec_cmd("skwd-wall-v2"))

# KDE Plasma - Use the shortcut app or launch through your launcher
skwd-wall-v2

Research how to do this in your specific compositor.

Installation

Arch Linux, CachyOS, EndevourOS, Manjaro, Garuda Linux etc.

# These are terminal commands!
# AUR - downloads prebuilt binaries so you don't have to compile a ton of Rust.
# If you want to compile a ton of rust, simply drop the -bin on the two packages
yay -S skwd-wall-v2-bin skwd-lens-bin

# Required only if you use KDE Plasma
yay -S skwd-paper-plasma

# Enable the wallpaper daemon
systemctl --user daemon-reload
systemctl --user enable --now skwd-walld.service

# Run using:
skwd-wall-v2

NixOS

# Enable flakes if you don't already use them
nix --extra-experimental-features 'nix-command flakes'

# Install
nix profile install github:liixini/skwd-wall/nix#default

# If you're using KDE Plasma you need the KDE Plasma plugin
nix profile install github:liixini/skwd-wall/nix#skwd-paper-plasma

# run with (or put in a keybind, convenient script... up to you)...
skwd-wall-v2

Fedora, Nobara etc.

# These are terminal commands!
# COPR
sudo dnf install dnf-plugins-core
sudo dnf copr enable piixini/skwd-wall-v2
sudo dnf install skwd-wall-v2 skwd-lens

# Required only if you use KDE Plasma
sudo dnf install skwd-paper-plasma

# Enable the wallpaper daemon
systemctl --user daemon-reload
systemctl --user enable --now skwd-walld.service

# Run using:
skwd-wall-v2

Bazzite KDE Plasma

# These are terminal commands!
# COPR
sudo dnf5 copr enable piixini/skwd-wall-v2 &&
sudo rpm-ostree install \
  skwd-wall-v2 skwd-deck skwd-paper \
  skwd-lens skwd-lens-model skwd-paper-plasma

# Reboot!
reboot

# Install the daemon that keeps wallpapers applied on reboot etc.
systemctl --user daemon-reload
systemctl --user enable --now skwd-walld.service

# Run using the below command, or keybind it or search for skwd-wall in your app launcher:
skwd-wall-v2

Debian, Ubuntu, Linux Mint etc - WIP

Open the wallpaper mixer directly from a launcher or keybinding:

skwd-wall-v2 --mixer

This starts Wall on the mixer screen, or opens the mixer in the running instance.

Compositor-specific tweaks

Niri overview wallpaper

In Settings > Playback > Video, set Wallpaper layer to Background, then add this to your Niri configuration:

layer-rule {
    match namespace="^skwd-paper-backdrop$"
    place-within-backdrop true
}

Enable Animate only in Niri overview to pause the active wallpaper while the overview is closed. Manual, process, and fullscreen pause rules still apply when it opens. The separate overviewBackdrop option keeps its existing behaviour.

KDE Plasma

Optional - Steamcmd or Steam Client

To retrieve wallpapers from Wallpaper Engine you have two options.

Skwd-wall can use Steamcmd or we can use your already installed Steam Client and pretend we're Wallpaper Engine. E.g. if you want it to just work with the caveat of opening Steam - use option 2. If you want a robust option that works simply by opening Skwd-wall but requires you acquiring a Steam Web API key, use option 1. Mind you the Steam Client integration is WIP and may not work on all platforms (even though it should).

API key + steamcmd (recommended): add a Steam Web API key and set the backend to steamcmd. Browsing and downloads both work, no running Steam needed.

Steam Client: install the optional skwd-deck-steamworks package and keep native Steam running. The Fedora COPR install does not include this helper. Use SteamCMD if you have not installed the separate companion RPM.

You won't have to interact with Steamcmd more than logging in once so that Skwd-wall can use your logged in Steamcmd to browse the Workshop and download Wallpaper Engine workshop items (wallpapers) for you and Skwd-wall will warn you if your token has expired or needs refreshing (read: you need to log into Steam again).

Skwd-wall does not handle any of your Steam credentials - this is all done through Valve's Steamcmd - it simply tries to use Steamcmd and either you're logged in or you're not. This means that I will not be implementing in-app login flows for this - I do not wish to handle any authentication and I leave this solely on the shoulders of Valve.

Semantic Search

Skwd-wall uses SigLIP2 8/16 as the default multilingual vision-language encoder. If all of that made you feel like you aren't reading English, essentially SigLIP2 tags pictures in many languages which allows us to retrieve the correct match when you search for "Outono fofo e aconchegante", "cute cozy autumn" or "Süßer gemütlicher Herbst". However, SigLIP2 8/16 is a "middle of the road" model chosen for a low footprint, and Skwd-wall supports plugging in more powerful models should you have access to hardware that is suited for it.

Skwd-wall automatically saves indexes any encoder has generated per model, meaning you can use as many as you wish and Skwd-wall will automatically index new wallpapers since your last use of a model.

Acknowledgements

Ilyamiro1 for the 250 IQ idea to use duckduckgo to retrieve wallpapers which made me realise wallhaven.cc & Steam have API:s for similar functionality. Also for implementing my ideas of parallelogram animations and colour sorting in his wallpaper selector - just happy people like my whacky ideas.

Horizon0427 for his excellent hexagon wallpaper selector from which I designed my hexagon style presentation entirely, with added animations and other features.

Happyzxzxz for showing me the Nix wizard way to do NixOS things.

Harman1307 for Iris which I have reimplemented in large parts and extended.

Achno for Gowall which I have reimplemented using Rust and similarly extended.

InioX for Matugen that powers a lot of the WIP bridges between Pywal et. al. that I'm building.