GNOME Dynamic Wallpapers and Wallpaper Positioning

This guide explains the technical mechanisms the GNOME desktop environment uses to manage custom wallpaper positioning and dynamic day-to-night transitions. GNOME relies on its GSettings configuration database to control image placement and display modes, while dynamic time-shifting backgrounds and light/dark mode pairings are handled through structured XML definition files and dedicated system schema keys.

Wallpaper Positioning and Scaling in GNOME

GNOME controls how background images are fitted to monitors through the GSettings schema org.gnome.desktop.background. While the standard GNOME Settings graphical interface automatically crops and scales images to fill the display, advanced positioning options remain available via the command line or the GNOME Tweaks utility.

The specific key responsible for positioning is picture-options. It accepts several distinct parameters:

  • zoom: The default mode, which scales the image to fill the entire screen while maintaining the aspect ratio, cropping edges if necessary.
  • centered: Centers the wallpaper at its native resolution without scaling, leaving border colors around smaller images.
  • scaled: Scales the image up or down to fit inside the screen boundaries without cropping, potentially leaving letterboxing or pillarboxing bars.
  • stretched: Forces the image dimensions to match the display resolution exactly, distorting the aspect ratio.
  • spanned: Stretches a single large wallpaper continuously across a multi-monitor layout instead of duplicating it on each display.
  • none: Disables the image entirely, rendering a solid background color configured in the primary-color key.

Users can modify this behavior directly in the terminal using the following command:

gsettings set org.gnome.desktop.background picture-options 'centered'

Day-Night Switching in Modern GNOME

Starting with GNOME 42, the desktop introduced a system-wide dark style preference. GNOME handles binary day-and-night wallpaper switching using dual GSettings keys:

  • picture-uri: Stores the file path for the light version of the wallpaper.
  • picture-uri-dark: Stores the file path for the dark version of the wallpaper.

When a user toggles the global dark style switch in the quick settings menu or control center, GNOME automatically alternates between the values set in these two keys without requiring external scripts.

Continuous Time-Based Dynamic Wallpapers via XML

For wallpapers that transition smoothly across multiple times of day (such as sunrise, afternoon, and night), GNOME utilizes an XML-based scheduling system. These XML files dictate image sequencing, durations, and crossfade transitions based on the system clock.

A dynamic background XML file typically resides alongside image assets in /usr/share/backgrounds/ or the user-specific directory ~/.local/share/backgrounds/. The XML file structure relies on three primary elements:

  1. <starttime>: Defines the base timestamp (year, month, day, hour, minute, second) from which transition cycles are calculated.
  2. <static>: Specifies the duration (in seconds) for displaying a specific image file via the <file> sub-tag.
  3. <transition>: Defines a gradual blend over a set duration from a <from> file to a <to> file.

A simplified XML implementation follows this layout:

<background>
  <starttime>
    <year>2024</year>
    <month>01</month>
    <day>01</day>
    <hour>07</hour>
    <minute>00</minute>
    <second>00</second>
  </starttime>
  
  <!-- Display daytime image for 14400 seconds (4 hours) -->
  <static>
    <duration>14400.0</duration>
    <file>/path/to/day.jpg</file>
  </static>
  
  <!-- Transition to evening over 1 hour -->
  <transition>
    <duration>3600.0</duration>
    <from>/path/to/day.jpg</from>
    <to>/path/to/night.jpg</to>
  </transition>
  
  <!-- Display nighttime image -->
  <static>
    <duration>14400.0</duration>
    <file>/path/to/night.jpg</file>
  </static>
</background>

System Registration and Appearance

To make dynamic or day-night paired backgrounds visible within the native GNOME Settings background picker, a metadata file must be placed in /usr/share/gnome-background-properties/ or ~/.local/share/gnome-background-properties/.

This property XML informs the desktop of the wallpaper's capabilities:

<?xml version="1.0"?>
<!DOCTYPE wallpapers SYSTEM "gnome-wp-list.dtd">
<wallpapers>
  <wallpaper deleted="false">
    <name>Dynamic Wallpaper</name>
    <filename>/path/to/dynamic-schedule.xml</filename>
    <options>zoom</options>
    <pcolor>#000000</pcolor>
    <scolor>#000000</scolor>
  </wallpaper>
</wallpapers>

When an XML schedule or dual-theme setup is loaded, the GNOME Control Center identifies the background as dynamic and marks it with a small badge, enabling the desktop environment to coordinate background aesthetics with system themes and local time automatically.