Skip to content

Installation

Jump to bottom
David Goree edited this page Sep 18, 2026 · 5 revisions

Installation

Pick the path that matches your distro.

Arch Linux (AUR)

The simplest install. This project is published on the AUR as wallpaper-engine-kde-plugin-new-fork.

yay -S wallpaper-engine-kde-plugin-new-fork
# or
paru -S wallpaper-engine-kde-plugin-new-fork

⚠️ Do not install wallpaper-engine-kde-plugin-git — that AUR package points at the original catsout repo, not this project. If you have it, remove it first:

yay -R wallpaper-engine-kde-plugin-git

After install, restart Plasma:

systemctl --user restart plasma-plasmashell.service

Then continue to First-Run Setup.

Fedora / Bazzite / rpm-ostree (COPR)

Prebuilt RPMs come from the project's COPR, captsilver666/wallpaper-engine-kde-plugin. It rebuilds on every push to main, so it is never behind a GitHub release, and updates arrive through the normal package manager.

⚠️ Other COPR projects also go by wallpaper-engine-kde-plugin and track older forks. Use the captsilver666 coordinates below, not a COPR search result.

Bazzite, Silverblue, Kinoite and other rpm-ostree systems:

sudo dnf5 copr enable captsilver666/wallpaper-engine-kde-plugin
sudo rpm-ostree install wallpaper-engine-kde-plugin-qt6
systemctl reboot

Install by package name, never from a downloaded .rpm file. rpm-ostree install ./some.rpm pins that exact file forever and never picks up a newer build. A package layered by name is re-resolved from the repo on every rpm-ostree upgrade — see Updating.

No dnf5 on your image? Fetch the repo file directly instead of the copr enable line:

sudo curl -o /etc/yum.repos.d/_copr:copr.fedorainfracloud.org:captsilver666:wallpaper-engine-kde-plugin.repo \
    "https://copr.fedorainfracloud.org/coprs/captsilver666/wallpaper-engine-kde-plugin/repo/fedora-$(rpm -E %fedora)/captsilver666-wallpaper-engine-kde-plugin-fedora-$(rpm -E %fedora).repo"

Standard Fedora:

sudo dnf copr enable captsilver666/wallpaper-engine-kde-plugin
sudo dnf install wallpaper-engine-kde-plugin-qt6
systemctl --user restart plasma-plasmashell.service

Builds are x86_64 only. The COPR page lists the Fedora releases currently served; openSUSE Tumbleweed and Mageia builds from the same spec are there too.

Video codecs on Fedora

Fedora's ffmpeg-free leaves out patent-encumbered codecs, so some video wallpapers won't play until you swap in the full ffmpeg from RPM Fusion. Bazzite already ships full codecs; on standard Fedora:

sudo dnf install -y \
    https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
    https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
sudo dnf swap -y ffmpeg-free ffmpeg --allowerasing

Then continue to First-Run Setup.

Ubuntu / Debian (.deb)

Download the .deb from the Releases page. You need Ubuntu 25.04+ or Debian Trixie+; anything older ships a Qt that is too old.

sudo apt install ./wallpaper-engine-kde-plugin_*.deb
systemctl --user restart plasma-plasmashell.service

Then continue to First-Run Setup.

Arch — build from source

sudo pacman -S --needed base-devel clang llvm cmake ninja extra-cmake-modules \
    vulkan-headers vulkan-icd-loader plasma-workspace plasma5support libplasma plasma-activities \
    kconfig kcoreaddons kpackage knotifications kcrash kglobalaccel ki18n kxmlgui \
    qt6-base qt6-declarative qt6-webchannel qt6-webengine \
    mpv lz4 freetype2 fontconfig libpulse libglvnd mesa

Then continue with the generic build steps.

Fedora — build from source

Everything needed to build is in Fedora's own repos; RPM Fusion is not required for the build.

sudo dnf install cmake extra-cmake-modules clang ninja-build vulkan-headers vulkan-loader-devel \
    plasma-workspace-devel libplasma-devel plasma-activities-devel plasma5support \
    kf6-kcoreaddons-devel kf6-kpackage-devel kf6-kconfig-devel kf6-knotifications-devel \
    kf6-kcrash-devel kf6-kglobalaccel-devel kf6-kxmlgui-devel kf6-ki18n-devel \
    qt6-qtbase-devel qt6-qtbase-private-devel qt6-qtdeclarative-devel \
    qt6-qtwebchannel-devel qt6-qtwebengine-devel \
    freetype-devel fontconfig-devel pulseaudio-libs-devel mpv-devel lz4-devel \
    libglvnd-devel mesa-libgbm-devel

plasma5support is a runtime QML import rather than a build input, but the wallpaper draws nothing without it.

Then continue with the generic build steps. For video wallpapers you'll probably also want the full ffmpeg.

On immutable Fedora derivatives (Bazzite, Silverblue, Kinoite) don't build on the host — install from the COPR, or build the RPM in a toolbox and layer it.

Generic build from source

You need the toolchain and dev headers from the Arch or Fedora list above; on another distro, translate those package names.

Build and install:

# Clone the repo
git clone https://github.com/captsilver/wallpaper-engine-kde-plugin.git
cd wallpaper-engine-kde-plugin

# Pull submodules (the scene renderer lives in src/ as a submodule)
git submodule update --init --force --recursive

# Configure + build (the project builds with Clang)
CC=clang CXX=clang++ cmake -B build -S . -DCMAKE_BUILD_TYPE=Release -G Ninja
cmake --build build

# Install system-wide
sudo cmake --install build

# Reload Plasma
systemctl --user restart plasma-plasmashell.service

Building the RPM yourself

Only worth it if you need a local change packaged. Everyone else should use the COPR.

One command

tools/scripts/build-packages.sh rpm creates a Fedora distrobox, installs the build dependencies in it and runs the two steps from the manual route below. Run it from the host; it needs only git and distrobox there, which makes it the route for Bazzite, Silverblue and Kinoite.

git clone https://github.com/captsilver/wallpaper-engine-kde-plugin.git
cd wallpaper-engine-kde-plugin
tools/scripts/build-packages.sh rpm

The finished RPM is copied to ~/wallpaper-engine-kde-plugin-qt6-*.rpm.

By hand

On a Fedora machine, or inside a Fedora toolbox on an immutable host:

sudo dnf install rpm-build git
git clone https://github.com/captsilver/wallpaper-engine-kde-plugin.git
cd wallpaper-engine-kde-plugin

# Build dependencies from the spec
sudo dnf builddep ./rpm/wek.spec

# Pack the source RPM. This inits the submodules itself, recursively, every time.
tools/scripts/make-srpm.sh --outdir ~/srpm

# Build the binary RPM from it
rpmbuild --rebuild ~/srpm/*.src.rpm

The finished RPM lands in ~/rpmbuild/RPMS/x86_64/.

Install the result

From the host. The paths below are for the one-command route; a by-hand build is under ~/rpmbuild/RPMS/x86_64/ instead.

# Standard Fedora
sudo dnf install ~/wallpaper-engine-kde-plugin-qt6-*.rpm

# rpm-ostree (Bazzite, Silverblue, Kinoite)
sudo rpm-ostree install ~/wallpaper-engine-kde-plugin-qt6-*.rpm
systemctl reboot

A package layered from a file stays pinned to that file; rpm-ostree upgrade won't replace it. Updating covers swapping in a newer build.

Continue to First-Run Setup.

Repo · Scene Renderer · GPL-2.0

Getting Started

Reference

Troubleshooting

Maintenance

About

Clone this wiki locally