How to create GNOME dynamic wallpapers

GNOME (GNU Network Object Model Environment), is one of the most popular desktop environments on Linux, and probably the most used one, since all major distributions use it as their default interface. Version 42 of the D.E., introduced a global “light/dark” UI mode switch, which is respected by all GNOME applications and wallpapers: switching the global style to “dark”, automatically changes the GTK theme to Adwaita-dark, and all the wallpapers supporting this feature, to their “dark” versions. GNOME also supports time-shifting wallpapers.

In this tutorial we learn how to create time-shifting and dynamic wallpapers that follow GNOME global style.

In this tutorial you will learn:

  • How to create a dynamic wallpaper that changes depending on GNOME global UI style
  • How to create a time-shifting wallpaper
How to create GNOME dynamic wallpapers
How to create GNOME dynamic wallpapers
Software Requirements and Linux Command Line Conventions
Category Requirements, Conventions or Software Version Used
System Distribution agnostic
Software A text editor
Other None
Conventions # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command
$ – requires given linux-commands to be executed as a regular non-privileged user

Creating a dynamic wallpaper

For the sake of this tutorial, I will use two images which are pretty similar: both have a blue background with a “tag” symbol in the center, which in one image is white, and in the other is black. We will use the former when GNOME is in “light” mode, and the latter when the “dark” mode is set:

the images which will compose our dynamic wallpaper
The images which will compose our dynamic wallpaper

All we have to do is place the pictures in a subdirectory under ~/.local/share/backgrounds, if we want to make the dynamic wallpaper available only for our user, or under /usr/share/backgrounds if we want to install it system-wide. In this case, we will use the first strategy. To reflect the “subject” of the images, we will create a directory named “tag”, and copy the two images, named respectively “tag-l.jpg” and “tag-d.jpg”, inside of it:

$ mkdir -p ~/.local/share/backgrounds/tag
$ cp tag-l.jpg tag-d.jpg ~/.local/share/backgrounds/tag

Once the images are in place, we have to create the XML file which specifies how they should be used. The XML file must be placed under the ~/.local/share/gnome-background-properties directory for user-level installations, or under /usr/share/gnome-background-properties for system ones. The name of the file is not important, however, to be consistent, we save it as tag.xml. Here is its content:

<?xml version="1.0"?>
<!DOCTYPE wallpapers SYSTEM "gnome-wp-list.dtd">
<wallpapers>
  <wallpaper deleted="false">
    <name>Tag</name>
    <filename>/home/doc/.local/share/backgrounds/tag/tag-l.jpg</filename>
    <filename-dark>/home/doc/.local/share/backgrounds/tag/tag-d.jpg</filename-dark>
    <options>zoom</options>
  </wallpaper>
</wallpapers>

The file can contain multiple wallpaper definitions. Each wallpaper is defined between “<wallpaper></wallpaper>” tags. With the “<name>” tag, we specify the name of the wallpaper, while with the “<filename>” and “<filename-dark>” tags, we define the absolute paths of the wallpapers which should be used in the “light” and “dark” mode, respectively.

Finally, with the “<options>” tag, we specify how the wallpaper should be rendered. Here “zoom” is what we want to use most of the time, since it fills the screen by zooming on the picture when needed, respecting its proportions; other possible values are: “none”, “wallpaper”, “centered”, “scaled”, “stretched” and “spanned”.

At this point, we should be ready. If we open the “appearance” panel in GNOME settings app, we should see our dynamic wallpaper nicely displayed as an option:

our dynamic wallpaper displayed in GNOME appearance panel
Our dynamic wallpaper displayed in GNOME appearance panel.

The light/dark variants of the wallpaper will be applied when we change GNOME global UI style:

Creating time-shifting wallpapers

Beside having the light/dark variants of our wallpaper applied accordingly to the GNOME global UI style, we can make sure they are shifted after a specified period of time. It would be nice, for example, to have the light variant of the wallpaper applied during the day, and the dark one to be set in the evening. To accomplish this, all we have to do is to create another XML file, and, for convenience, place it in the same directory where the pictures composing our dynamic wallpaper are. In this case, we will save it as ~/.local/share/backgrounds/tag/tag.xml.



Inside the file, we specify how and when the images should be applied. Here is an example:

<background>
  <starttime>
    <year>2023</year>
    <month>1</month>
    <day>1</day>
    <hour>8</hour>
    <minute>0</minute>
    <second>0</second>
  </starttime>
  <static>
    <file>/home/doc/.local/share/backgrounds/tag/tag-l.jpg</file>
    <duration>36000</duration>
  </static>
  <transition type="overlay">
    <duration>7200</duration>
    <from>/home/doc/.local/share/backgrounds/tag/tag-l.jpg</from>
    <to>/home/doc/.local/share/backgrounds/tag/tag-d.jpg</to>
  </transition>
  <static>
    <file>/home/doc/.local/share/backgrounds/tag/tag-d.jpg</file>
    <duration>36000</duration>
  </static>
  <transition type="overlay">
    <duration>7200</duration>
    <from>/home/doc/.local/share/backgrounds/tag/tag-d.jpg</from>
    <to>/home/doc/.local/share/backgrounds/tag/tag.l.jpg</to>
  </transition>
</background>

This configuration will be effective starting from 1/1/2023 at 8:00. The first image which will be applied, at that hour, will be the “light” variant of the “tag” wallpaper: it will last for 36000 seconds (10 hours). After that period of time, at 18:00, the transition will start, and will last 7200 seconds (2 hours), until 20:00. At 20:00 the dark variant of the image will be displayed for 10 hours, so until 6:00. At 6:00 another transition will start, and last 2 hours, until 8:00. This procedure will be repeated each day.

One last thing needs to be done: we have to reference the file we just wrote, in the XML we previously created under ~/.local/share/gnome-background-properties, by adding another <wallpaper></wallpaper section:

<wallpaper deleted="false">
  <name>Tag Time of Day</name>
  <filename>/home/doc/.local/share/backgrounds/tag/tag.xml</filename>
  <options>zoom</options>
</wallpaper>

In the background selector settings, we should now notice the time-shifting wallpaper, which can be identified by the timer icon in the bottom left of the thumbnail:

Creating dynamic wallpapers with the “Dynamic Wallpaper” tool

To ease the creation of dynamic wallpapers, we can use the open source “Dynamic Wallpaper” tool, which is available as a flatpak on Flathub. The tool allows us to select the “light” and “dark” images which compose our wallpaper and creates all required files and directories for us:

The Dynamic Wallpaper tool
The Dynamic Wallpaper tool



A tool with a similar name, “Dynamic Wallpaper Editor”, is also available on Flathub (and as an rpm package in the Fedora official repositories): it can be used to create time-shifting wallpapers. The tool let us select the images we want to use and set how much time they should last, together with transitions:

The Dynamic Wallpaper Editor tool
The Dynamic Wallpaper Editor tool

Closing thoughts

In this tutorial, we learned how to create dynamic and time-shifting wallpapers. The former change accordingly to the GNOME global UI style, the images composing the latter, instead, shift after a specified period of time. The behavior of dynamic wallpapers is defined via XML files; we saw how to create them with a simple text editor or by using dedicated graphical tools such as “Dynamic Wallpaper” and “Dynamic Wallpaper Editor”.