A simple command line tool which can read and set the desktop picture/wallpaper. Credit for the name to Neil Martin.
Note: Apple used to call the macOS background image 'desktop picture' until macOS 13 Ventura, when they changed to be the same as in iOS: 'wallpaper'. This documentation might use either term.
I have written a few blog posts that describe different use strategies for setting a desktop picture:
- Using desktoppr in a managed environment
- Building a LaunchD Installer pkg for desktoppr (and other tools)
- Strategies to using desktoppr
- Random Desktop Background with desktoppr
You can read the current desktop picture/wallpaper with:
$ desktoppr
/Library/Desktop Pictures/Sierra.jpg
and set the desktop picture with
$ desktoppr "/Library/Desktop Pictures/BoringBlueDesktop.png"
When you have multiple displays, desktoppr will list all desktop pictures:
$ desktoppr
/Library/Desktop Pictures/HotStepper.jpg
/Library/Desktop Pictures/LyricalGangster.jpg
/Library/Desktop Pictures/MrOfficer.jpg
When you pass a file desktoppr will set it as the desktop picture for all screens:
$ desktoppr /Library/Desktop Pictures/NaahNananah.jpg
$ desktoppr
/Library/Desktop Pictures/NaahNananah.jpg
/Library/Desktop Pictures/NaahNananah.jpg
/Library/Desktop Pictures/NaahNananah.jpg
You can also set the desktop for a specific screen: (index starts at zero)
$ desktoppr 0 /Library/Desktop Pictures/HotStepper.jpg
$ desktoppr 1 /Library/Desktop Pictures/LyricalGangster.jpg
$ desktoppr 2 /Library/Desktop Pictures/MrOfficer.jpg
desktoppr can also control the image scaling and background color for the desktop picture.
The scale and color settings will be set for all screens.
Use the scale verb to control how the desktops are scaled. It can have the values fill (default), stretch, center, or fit.
$ desktoppr scale center
You can pass a hex string for the background color:
$ desktoppr color 000000 # black background
$ desktoppr color FFFFFF # white background
$ desktoppr color FF0000 # red background
Setting the wallpaper, scale and/or color are separate commands.
Note: setting the background color does not work in macOS 14.x. See issue #22.
When you give a URL to an image file as the argument, desktoppr will download the file from the URL and set it as the wallpaper.
$ desktoppr https://raw.githubusercontent.com/scriptingosx/desktoppr/profile/examples/BoringBlueDesktop.png
The downloaded file will be stored in ~/Library/Application Support/desktoppr/.
When the download fails, the wallpaper will not be changed. If the downloaded file is not an image file, the wallpaper will revert to the system default.
When you want to run it from a script it is safest to include the entire path to the binary:
/usr/local/bin/desktoppr "/Library/Desktop Pictures/BoringBlueDesktop.png"
Since the desktoppr tool sets user preferences, you still need to pay attention that it runs as the user. A LaunchAgent or a solution like outset is a good choice to manage this. Alternatively, you can run the command as the current user from a root script.
When you run desktoppr with the manage verb, it will read the settings from the com.scriptingosx.desktoppr preference domain. You can set these settings with the defaults command or, preferably, by pushing a configuration profile from an MDM server.
The idea is to run desktoppr manage with a LaunchAgent plist at login and/or at regular intervals. You can find a sample LaunchAgent plist here. The sample LaunchAgent will run desktoppr manage at login and every three hours (10800 sec). You can build a pkg that installs the desktoppr binary, the LaunchAgent plist and an image file very early in the deployment workflow and then desktoppr sets the desktop background when the user reaches the desktop for the first time.
For Ventura and higher, binaries and applications run by LaunchAgents need to be approved with a com.apple.servicemanagement profile so they appear as managed in the login items section in Settings.app. The sample configuration profile contains those settings, as well.
desktoppr uses the following keys:
The path to the image file for the desktop picture/wallpaper. The same image will be set for all screens.
When the value starts with http:// or https:// desktoppr will interpret this as a URL and attempt to download a file and set that file as the desktop picture/wallpaper. The downloaded file will be stored in ~/Library/Application Support/desktoppr/. You can have desktoppr verify the downloaded image file by providing a sha256 checksum.
This sha256 checksum will be used to verify the downloaded image file. If the checksum from the downloaded file does not match the value of this key, the desktop picture/wallpaper will not be changed.
You can generate the sha256 checksum of the image file with shasum -a 256 <filepath>
This string will be interpreted as a six-digit hex code and set as the background color. (Note: setting the color is broken on macOS 14.x.)
One of fill (default), stretch, center, or fit. This controls the scaling behavior of the image.
When set to true, desktoppr manage will not re-set the desktop picture/wallpaper if the last picture desktoppr manage set was the same. Use this to set the desktop image/wallpaper once from a configuration profile but allow the user to change it afterward. Even when desktoppr manage runs frequently, it should only re-set the desktop picture/wallpaper when the setting in the configuration profile changes.
When set to false, desktoppr manage will re-apply the managed settings every time.
The examples have a sample defaults plist with keys and a sample configuration profile.
You can get the code for desktoppr on my Github page and an installer in the Releases. The installer pkg will install the binary in /usr/local/bin. Alternatively, a brew cask exists, so you could install it using brew install --cask desktoppr if you have Homebrew installed.
The tool requires the Swift 5 Runtime support for command line tools when you install it on versions of macOS older than 10.14.4.