Setting the Desktop Image in macOS Mojave from the Command Line

S

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/ folder 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/ folder along with all the other Apple-supplied non-dynamic Desktop images.

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 most interest are the data and preferences tables:

Default
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------

 

 

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/ folder points to. For a fresh macOS Mojave install this is Mojave.heic in the /Library/Desktop Pictures/ folder.

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

Dummy Content
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.

The examples are numbered 1.1, 1.2, … 2.1, … 3.1, … etc. Each x.1 represents the initial change 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.

1.1 Mojave Light (Still) :: previous Default
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
1212013
22014
32012
42011

 

 

1.2 Mojave (Dynamic) :: previous Mojave Light (Still)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
2152023
62024
72022
82021

 

 

1.3 Mojave Dark (Still) :: previous Mojave (Dynamic)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
3392033
102034
112032
122031

 

 

1.4 Solar Gradients :: previous Mojave Dark (Still)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
33132033
4/Library/Desktop Pictures/Solar Gradients.heic14143
152034
16144
172032
18142
192031
20141

 

 

1.5 Non-dynamic (High Sierra) :: previous Solar Gradients
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
33212033
5/Library/Desktop Pictures/High Sierra.jpg22153
232034
24154
252032
26152
272031
28151

 

 

2.1 Mojave Dark (Still) :: previous Default
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
1312013
22014
32012
42011

 

 

2.2 Non-dynamic (High Sierra) :: previous Mojave Dark (Still)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
1352013
2/Library/Desktop Pictures/High Sierra.jpg6123
72014
8124
92012
10122
112011
12121

 

 

2.3 Mojave (Dynamic) via Mojave Dark (Still) :: previous Non-dynamic (High Sierra)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
21172023
182024
192022
202021

 

 

2.4 Mojave Light (Still) :: previous Mojave (Dynamic)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
32212033
222034
232032
242031

 

 

2.5 Solar Gradients :: previous Mojave Light (Still)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
32252033
4/Library/Desktop Pictures/Solar Gradients.heic26143
272034
28144
292032
30142
312031
32141

 

 

2.6 Mojave Dark (Still) via Mojave Light (Still) :: previous Solar Gradients
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
43372043
382044
392042
402041

 

 

3.1 Solar Gradients :: previous Default
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
1/Library/Desktop Pictures/Solar Gradients.heic1113
2022023
3114
42024
5112
62022
7111
82021

 

 

3.2 Mojave Light (Still) via Mojave (Dynamic) :: previous Solar Gradients
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
32132033
142034
152032
162031

 

 

3.3 Mojave Dark (Still) :: previous Mojave Light (Still)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
43172043
182044
192042
202041

 

 

3.4 Mojave (Dynamic) :: previous Mojave Dark (Still)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
51212053
222054
232052
242051

 

 

3.5 Non-dynamic (High Sierra) :: previous Mojave (Dynamic)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
51252053
6/Library/Desktop Pictures/High Sierra.jpg26163
272054
28164
292052
30162
312051
32161

 

 

3.6 Mojave Light (Still) via Mojave (Dynamic) :: previous Non-dynamic (High Sierra)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
62372063
382064
392062
402061

 

 

4.1 Non-dynamic (High Sierra) :: previous Default
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
1/Library/Desktop Pictures/High Sierra.jpg1113
2114
3112
4111

 

 

4.2 Mojave Dark (Still) via Mojave (Dynamic) :: previous Non-dynamic (High Sierra)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
3392033
102034
112032
122031

 

 

4.3 Mojave Light (Still) :: previous Mojave Dark (Still)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
42132043
142044
152042
162041

 

 

5.1 Solar Gradients :: previous Mojave (Dynamic)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
1152013
2/Library/Desktop Pictures/Solar Gradients.heic6123
72014
8124
92012
10122
112011
12121

 

 

6.1 Non-dynamic (High Sierra) :: previous Mojave Light (Still)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
1252013
2/Library/Desktop Pictures/High Sierra.jpg6123
72014
8124
92012
10122
112011
12121

 

 

6.2 Solar Gradients :: previous Non-dynamic (High Sierra)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
12132013
3/Library/Desktop Pictures/Solar Gradients.heic14133
152014
16134
172012
18132
192011
20131

 

 

7.2 Mojave (Dynamic) :: previous Solar Gradients
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
2052023
62024
72022
82021

 

 

8.2 Non-dynamic (Ink Cloud) :: previous Non-dynamic (High Sierra)
-------------------- data table -------------------------- preferences table ------
rowidvaluerowidkeydata_idpicture_id
----------------------------------------------------------------------------
2/Library/Desktop Pictures/Ink Cloud.jpg5123
6124
7122
8121

 

 

These examples have led me to conclude the following. For brevity Mojave (Dynamic), Mojave Light (Still) and Mojave Dark (Still) images are referred to as dynamic images whereas Solar Gradients 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.1 and 6.1]. This is also true if the Desktop image subsequently changes to another standard image [1.5 and 6.2].

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 is not deleted [1.4, 2.2, 2.5, 3.5, 5.1 and 6.1]. 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.2].

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.1, 6.1 and 6.2].

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.1, 6.1, 6.2 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. A value of 1 for the value column in the data table is always used for the Mojave (Dynamic) Desktop image, never a 0. 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.

About the author

A native Brit exiled in Japan, Steve spends too much of his time struggling with the Japanese language, dreaming of fish & chips and writing the occasional blog post he hopes others will find helpful.

Add comment

Steve

Recent Comments

Recent Posts

Archives