Customize desktop backgrounds

As a system administrator, you can configure the default desktop background, add extra backgrounds, or add multiple backgrounds available to all users of the system.

By default, users are permitted to change the background. As an administrator, you can prevent users from changing the background with the settings in the locks directory.

Customize the default desktop background
Copy link

You can configure the default desktop background and its appearance by setting the relevant GSettings keys in the org.gnome.desktop.background schema.

Procedure
Copy link

  1. Create a local database for machine-wide settings in /etc/dconf/db/local.d/00-background: 
    [org/gnome/desktop/background]

picture-uri='file:///usr/local/share/backgrounds/wallpaper.jpg'
picture-options='scaled'
primary-color='000000'
secondary-color='FFFFFF'
    • picture-uri: Specify the path to the desktop background image file.
    • picture-options: Specify one of the rendering options for the background image:
      • none
      • wallpaper
      • centered
      • scaled
      • stretched
      • zoom
      • spanned
    • primary-color: Specify the left or top color when drawing gradients or the solid color.
    • secondary-color: Specify the right or bottom color when drawing gradients.
  2. Optional: If you want to prevent a user from changing the default background, override the user’s setting in the /etc/dconf/db/local.d/locks/background file: 
    # List the keys used to configure the desktop background
/org/gnome/desktop/background/picture-uri
/org/gnome/desktop/background/picture-options
/org/gnome/desktop/background/primary-color
/org/gnome/desktop/background/secondary-color
  3. Update the system databases: 
    # dconf update
  4. Users must log out and back in again before the system-wide settings take effect.

Screen shield
Copy link

The screen shield is the screen that slides down when you lock the system.

Starting with GNOME 40, GNOME Shell no longer supports a separate image for the screen shield. The lock screen displays a blurred version of your current desktop background. To customize what appears on the screen shield, configure the desktop background image system-wide as described in the Customizing the default desktop background section.

Add extra backgrounds
Copy link

You can make extra backgrounds available to users on your system.

Procedure
Copy link

  1. Create the /usr/share/gnome-background-properties/extra-backgrounds.xml file.
  2. In the new file, specify the extra background files and their appearance in the following format: 
    <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE wallpapers SYSTEM "gnome-wp-list.dtd">
<wallpapers>
  <wallpaper deleted="false">
    <name>Background name</name>
    <filename>full-path-to-the-image</filename>
    <options>display-option</options>
    <shade_type>background-shade</shade_type>
    <pcolor>primary-color</pcolor>
    <scolor>secondary-color</scolor>
  </wallpaper>
</wallpapers>
  3. The new backgrounds are now available to all users in the Background section of the Settings application.

Frequently used background schema keys
Copy link

The following configuration controls the behavior of desktop backgrounds in the GSettings system.

Table 1. Frequently used GSettings and XML background keys
Key name XML name Possible values Description

picture-options

options

  • none
  • wallpaper
  • centered
  • scaled
  • stretched
  • zoom
  • spanned

Determines how the image set by wallpaper_filename is rendered.

color-shading-type

shade_type

  • horizontal
  • vertical
  • solid

Determines the shade of the background color.

primary-color

pcolor

default: #023c88

Left or Top color when drawing gradients, or the solid color.

secondary-color

scolor

default: #5789ca

Right or Bottom color when drawing gradients, not used for solid color.

An extra backgrounds file with one element
Copy link

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE wallpapers SYSTEM "gnome-wp-list.dtd">
<wallpapers>
  <wallpaper deleted="false">
    <name>Company Background</name>
    <name xml:lang="de">Firmenhintergrund</name>
    <filename>/usr/local/share/backgrounds/company-wallpaper.jpg</filename>
    <options>zoom</options>
    <shade_type>solid</shade_type>
    <pcolor>#ffffff</pcolor>
    <scolor>#000000</scolor>
  </wallpaper>
</wallpapers>

An extra backgrounds file with two elements
Copy link

In one configuration file, you can specify multiple <wallpaper> elements to add more backgrounds as shown in the following example with two <wallpaper> elements, adding two different backgrounds.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE wallpapers SYSTEM "gnome-wp-list.dtd">
<wallpapers>
  <wallpaper deleted="false">
    <name>Company Background</name>
    <name xml:lang="de">Firmenhintergrund</name>
    <filename>/usr/local/share/backgrounds/company-wallpaper.jpg</filename>
    <options>zoom</options>
    <shade_type>solid</shade_type>
    <pcolor>#ffffff</pcolor>
    <scolor>#000000</scolor>
  </wallpaper>
  <wallpaper deleted="false">
    <name>Company Background 2</name>
    <name xml:lang="de">Firmenhintergrund 2</name>
    <filename>/usr/local/share/backgrounds/company-wallpaper-2.jpg</filename>
    <options>zoom</options>
    <shade_type>solid</shade_type>
    <pcolor>#ff0000</pcolor>
    <scolor>#00ffff</scolor>
  </wallpaper>
</wallpapers>