How to Sync Wallpapers with Themes in KDE Plasma

When I first started using KDE Plasma as my daily driver a few months back, I really loved it. Perhaps I just grew tired of using the same stale Windows desktop that I've been using for two decades, but I can say that using Plasma made me excited to use my computer again. Plasma is perhaps most well-known for how customizable it is, but there was one thing I wanted to do that I just couldn't seem to figure out: change my wallpaper when I switch between light and dark themes.

While many people seem to pick a theme and stick with it, I find myself switching between them quite often depending on the amount of ambient light in the surrounding environment. The problem I run into is that I'm blinded if I have a bright wallpaper at night, and I can't see my computer screen if I have a dark wallpaper in a well-lit room. Manually changing my wallpaper every time I switch themes feels tedious, so I figured there has to be a better way. Luckily, there is!

Tutorial

Make sure you have the two pictures you want to swap between when you change themes, ideally a lighter one and a darker one. I'll be using the following images:

Light Theme

(Image by sorin on Artstation)

Dark Theme

(Image by 唐蛋白 on pixiv)

(The art is of characters and locations from Xenoblade Chronicles 3, if you're curious!)

Navigate to ~/.local/share/wallpapers. Create a new folder to hold your wallpapers and give it a relevant title.

Go into that folder and create a file called metadata.json. Open it with your favorite editor and paste the following:

{
    "KPlugin": {
        "Id": "XC3-Light-Dark",
        "Name": "XC3 Light/Dark Theme"
    }
}

This data is necessary for Plasma to correctly identify the wallpapers. The "Id" key must be a unique value (i.e. just make sure you don't have another metadata.json file in ~/.local/share/wallpapers with the same "Id"). The "Name" key is the title that will actually show up next to your wallpapers. Name it whatever makes sense for you.

Once this is done, save and close the file.

Next, create a directory titled contents in ~/.local/share/wallpapers.

Within the contents directory, create two more directories: one titled images and another titled images_dark. This is where Plasma will look for the image files, so go ahead and copy your wallpapers to their respective locations (light wallpaper into images, dark wallpaper into images_dark).

Even though our wallpapers are now in the folders where they need to be, we're not quite done yet. If we try to change our wallpaper by opening System Settings and navigating to Appearance & Style > Wallpaper, we can see that our wallpaper is there, but it looks a little bit different than the rest of them. Instead of just showing an image of the wallpapers, they appear to be inside of a folder.

If you try to apply the theme right now, it won't work. What you need to do first is rename both images to reflect their respective resolutions. If you don't know the resolution of an image, you can easily figure it out by right clicking on the image > Properties, clicking the details tab and reading the "Dimensions" at the bottom. In the example below, I can see that my image is 1920x1106, so I am going to name my image exactly that (note that I did not include the comma in the updated filename).

Now, if you check your available wallpapers, you should see that the folder icon is no longer showing; instead, you should see a side-by-side of your light wallpaper on the left, and your dark wallpaper on the right.

You should be done! To apply your wallpaper, apply a different one first (this has helped prevent issues for me, so I recommend doing this), then apply the new one you just created. When you switch between light and dark themes, you should see that your wallpaper automatically changes along with it.

Light Theme

Dark Theme

In my opinion, the easiest way to swap between light and dark themes is to use the Day/Night Switcher widget. You'll be able to swap your theme and wallpaper with a single click!