Setting the Desktop Image in macOS Mojave From the Command Line

Prior to OS X Mavericks 10.9 a user’s Desktop image was stored in com.apple.desktop.plist located in the ~/Library/Preferences/ folder and changed from the command line using:

defaults write com.apple.desktop Background '{default = {ImageFilePath = "/path/to/desktop/image.jpg";};}'

Mavericks implemented an SQLite database named desktoppicture.db located in the ~/Library/Application Support/Dock/ directory to hold this information. A Desktop image could be changed from the command line using:

sqlite3 ~/Library/Application\ Support/Dock/desktoppicture.db "UPDATE data SET value='/path/to/desktop/image.jpg';"

macOS Mojave 10.14 ships with some High Efficiency Image Format (HEIF) Desktop images that Apple identify with a .heic extension and group in System Preferences under the category Dynamic Desktop. As of the initial Mojave release there are only two of these images: Mojave.heic and Solar Gradients.heic. They are located in the /Library/Desktop Pictures/ directory along with all the other Apple-supplied non-dynamic Desktop images.

Selecting Mojave as the Desktop image in System Preferences allows you to further choose between Dynamic, Light (Still) and Dark (Still). There are no such options when selecting Solar Gradients.

The desktoppicture.db file still exists in Mojave, so you’d be forgiven for thinking that changing a user’s Desktop image from the command line is the same as it’s been since Mavericks. However, the way dynamic Desktop images are stored is different to non-dynamic Desktop images.

Please note that the examples and conclusions below are relevant only where a user has a single Desktop (Space) in a single-display environment. They are not applicable where a user has more than one Desktop (Space) or in a dual-display environment.

Let’s first take a look at desktoppicture.db. This SQLite database contains 6 tables: data, displays, pictures, preferences, prefs and spaces. For the purposes of this article, the two tables of interest are the data and preferences tables:

The data and preferences tables for a newly created user are empty. They contain no rows. The default Desktop image for a new user is the image file that the symbolic link DefaultDesktop.heic in the /System/Library/CoreServices/ directory points to. For a fresh macOS Mojave install this is Mojave.heic in the /Library/Desktop Pictures/ directory.

NOTE: You may re-create the default desktoppicture.db from the command line at any time using:

killall System\ Preferences > /dev/null 2>&1 && rm ~/Library/Application\ Support/Dock/desktoppicture.db && killall Dock

To understand how macOS Mojave updates and maintains desktoppicture.db I changed the Desktop image numerous times in System Preferences noting the state of the data and preferences tables each time. While these examples are not exhaustive I believe they represent a large majority of the kind of changes it’s possible to make.

There are 8 sets of examples numbered 1.x, 2.x, 3.x etc. Each set begins with the initial change (x.1) to desktoppicture.db after it’s been reset to the default – referred to below as Default – with every subsequent point increment being a change to the same version of the database within a given set. The exceptions are sets 5, 6, 7 and 8 where the initial change is not shown so as not to duplicate previous examples.

Examples that contain the phrase via Mojave… do so because of the way System Preferences forces the user to make changes to a Desktop image. For example, the sequence of changes starting with Mojave Light (Still) to Solar Gradients to Mojave Dark (Still) is actually Mojave Light (Still) to Solar Gradients to Mojave Light (Still) to Mojave Dark (Still). This extra step with Mojave Light (Still) is because when selecting Mojave, System Preferences initially sets the Desktop image to the previously saved choice for Mojave i.e. Light (Still). The affect of this can be seen with the preferences table where the rowids are no longer consecutive with those in the previous example.

The following conclusions can be drawn from these examples. For clarity, Mojave (Dynamic), Mojave Light (Still) and Mojave Dark (Still) images are referred to as dynamic images whereas Solar Gradients – although a dynamic image – and non-dynamic images such as High Sierra are referred to as standard images:

1. The preferences table always contains 4 times the number of rows of the data table. The data table normally contains only a single row. The exception appears to be when the Desktop image has changed from a dynamic image to a standard image. In this instance the data table contains 2 rows [1.4, 2.2, 2.5, 3.5, 5.2 and 6.2]. This is also true if the Desktop image subsequently changes to another standard image [1.5 and 6.3].

2. When a Desktop image changes, all existing rows in the preferences table are deleted before new rows are added as is evident from the incremented row IDs. This is also true for the data table except where the Desktop image changes from a dynamic image to a standard image in which case the existing row appears not to be deleted [1.4, 2.2, 2.5, 3.5, 5.2 and 6.2]. In addition, if the Desktop image subsequently changes to another standard image only the row relating to the previous standard image is deleted before a new one is added [1.5 and 6.3].

3. If the data table and preferences table are empty – this is the default – and the Desktop image is set to Solar Gradients, two rows are added to the data table. The value column of one contains /Library/Desktop Pictures/Solar Gradients.heic the value column of the other contains 0 [3.1].

4. Where there are 2 rows in the data table – one relating to a dynamic image and the other relating a standard image – the Desktop image is set to the standard image [1.4, 1.5, 2.2, 2.5, 3.1, 3.5, 5.2, 6.2 and 6.3].

5. When the Desktop image is Mojave (Dynamic) the value column of the data table is 1 [1.2, 2.3 and 3.4]. There appears to be an exception to this when the previous Desktop image was Solar Gradients in which case it is 0 [7.2].

6. When the Desktop image is Mojave Light (Still) the value column of the data table is 2 [1.1, 2.4, 3.2, 3.6 and 4.3].

7. When the Desktop image is Mojave Dark (Still) the value column of the data table is 3 [1.3, 2.1, 2.6, 3.3 and 4.2].

8. When the Desktop image is a standard image the value column of the data table is /path/to/desktop/image.jpg [1.4, 1.5, 2.2, 2.5, 3.1, 3.5, 4.1, 5.2, 6.2, 6.3 and 8.2].

9. The relationship between the two tables is based upon the data table’s rowid column and the preferences table’s data_id column. The data_id column of rows in the preferences table is the same as the rowid in the data table. Where the preferences table has 8 rows, the data_id column for half of them is the rowid of the first row in the data table and the rowid of the second row for the other half.

10. Rows in the preferences table relating to dynamic images have a key column value of 20.

11. Rows in the preferences table relating to standard images have a key column value of 1.

Based upon my understanding I’ve put together a Bash script that allows a user’s Desktop image to be changed from the command line. Instructions can be found in the README.md.

While this script attempts to emulate System Preferences in how it maintains desktoppicture.db there are some notable differences which don’t appear to present any risk to the integrity of the database:

i. A value of 1 is always used for the value column in the data table for the Mojave (Dynamic) Desktop image, never a 0.

ii. All existing rows in the data and preferences tables are deleted first before adding new ones. This means that the maximum number of rows for these two tables at any given time is 1 and 4 respectively.