Wallhaven Wallpaper Reborn

Port of wallhaven wallpaper plugin by subpop for plasma 6.

Features

original features

• automatically change wallpaper at a set interval.
• Search for wallpapers by keyword.
• Filter by categories.
• Filter by Purity.
• Sort by Relevance, Random, Date Added, Views, Favorites, Toplist.
• Set wallpaper to fill, fit, stretch, center, tile, or scale.
• Use own API key (only required for accessing NSFW wallpapers).

New features

• Ported to plasma 6.
• add right click context menu action to open wallpaper in browser.
• add right click context menu action to fetch new wallpaper.
• streamline the settings page.
• allow using multiple tags as query parameters.
  • tags must be real wallhaven tag names (e.g. nature, landscape).
  • tags should be separated by commas.
  • one tag is chosen randomly from the list of tags for each wallpaper.
• add ability to pass a custom aspect ratio or multiple aspect ratios.
• add ability to pass a custom resolution.
• add tooltip button to show how to search for wallpapers.
• automatically refresh the wallpaper after changing settings.
• show notification when fetching new wallpaper or when an error occurs.
• add UI to allow toggling notifications.
• retry fetching wallpaper when a network error occurs.
• follow system color scheme to automatically fetch darker wallpapers in Dark Mode.
• save wallpapers to a personal collection with offline support.
  • right-click context menu to save the current wallpaper (downloaded locally).
  • use saved wallpapers only mode to cycle through your collection offline.
  • choose between looping through saved wallpapers or fetching new ones when exhausted.
  • shuffle saved wallpapers for random playback or display in sequential order.
  • open the saved wallpapers folder from settings.
  • clear all removes both the list and the local files.
  • automatically fetch from Wallhaven when saved list is empty.

Current known issues

• the plugin cannot be set as lock screen wallpaper. (networking related)
• the Wallpaper settings in the System Settings app does not work properly with this plugin. Use the right-click on the desktop → Configure Desktop and Wallpaper menu instead — this is the only supported way to configure the plugin. (check related issues #17, #30)

How to Search

the query field accepts the following types of entries, each matching the wallhaven API search syntax:

• tag name (fuzzy keyword search): nature, landscape, anime — must be real wallhaven tag names, not arbitrary words or numbers like tag1 or tag8621.
• exact tag by ID: id:1 — searches for wallpapers with the tag that has that numeric ID. find a tag's ID by looking at the URL of its page on wallhaven.cc. cannot be combined with other terms in the same entry.
• wallhaven username: @username — shows wallpapers uploaded by that user.
• similar wallpapers: like:abc123z — finds wallpapers similar to the one with that wallpaper ID (the alphanumeric ID from the wallhaven URL, e.g. wallhaven.cc/w/abc123z).
• comma-separated list: nature,landscape,@username,like:abc123z — the plugin picks one entry at random each time a new wallpaper is fetched, so each entry must be a valid standalone query.

if you are unsure what tags exist, browse wallhaven.cc and check the tags listed on any wallpaper page.

for more information about the wallhaven API, you can check the official documentation.

Saved Wallpapers

Build a personal collection of your favorite wallpapers with true offline use:

1. Save wallpapers: Right-click on the desktop → "Save Wallpaper" to download and store the current wallpaper locally.
2. Use saved wallpapers only: Enable this option in settings to cycle through your saved wallpapers without an internet connection.
3. Loop or fetch new: Choose whether to restart the cycle when all saved wallpapers have been shown, or automatically fetch new wallpapers from Wallhaven.
4. Shuffle or sequential: Display saved wallpapers in random order, or in the order they were saved.
5. Manage collection: Open the saved wallpapers folder from settings, or clear the entire collection (files included) with one click.

Saved wallpapers persist across plasmashell restarts and include thumbnail URLs for fast preview loading in settings.

Installation

Arch Linux

Install the plugin from the AUR (thanks to @cyqsimon for maintaining the package)

yay -S plasma6-applets-wallhaven-reborn-git

KDE Store

Install the plugin from the KDE Store Plasma 6 version

• Right click on the Desktop > Configure Desktop and Wallpaper... > Get New Plugins
• Search for "Wallhaven Wallpaper Reborn", install and set it as your wallpaper.
• Restart plasmashell if the wallpaper is not fetched or applied. (check Additional Setup below)

From source

installation requires kpackagetool6 which can be found on the kpackage package on arch based distros, kpackagetool6 on Suse based distros, and kf6-kpackage on debian based distros.

git clone https://github.com/Blacksuan19/plasma-wallpaper-wallhaven-reborn.git
cd plasma-wallpaper-wallhaven-reborn
kpackagetool6 --type Plasma/Wallpaper --install package/

# restart plasmashell
plasmashell --replace & disown

Additional Setup

If the wallpaper is not fetched or applied after installation, follow these steps before reporting a bug.

• Set the plugin as your wallpaper via right-click on the desktop → Configure Desktop and Wallpaper (do not use the System Settings app — see known issues).
• Close the settings window.
• Open the settings window again — a new wallpaper should be fetched.

If the wallpaper is still not fetched or applied:

• Refresh the wallpaper from the context menu or settings page.

• Restart the shell:

  plasmashell --replace & disown

Reporting Bugs

Please use the issue tracker to report bugs. The bug report template will guide you through providing all the necessary information.