sindresorhus / macos-wallpaper

Manage the desktop wallpaper on macOS

macos-wallpaper

Manage the desktop wallpaper on macOS

This is both a command-line app and a Swift package.

It correctly handles getting the active wallpaper even when the wallpaper is set to a directory.

CLI

Requires macOS 10.14.4 or later.

Install

Homebrew

brew install wallpaper

Manually

Download the binary and put it in /usr/local/bin.

Usage

By default, it sets and gets the wallpaper for all screens. Use the --screen flag to change this.

$ wallpaper

USAGE: wallpaper <subcommand>

OPTIONS:
  --version               Show the version.
  -h, --help              Show help information.

SUBCOMMANDS:
  get                     Get current wallpaper images.
  set                     Set image as wallpaper.
  set-solid-color         Set solid color as wallpaper.
  screens                 Get a list of available screens.

$ wallpaper get --help

OVERVIEW: Get current wallpaper images.

USAGE: wallpaper get [--screen <screen>]

OPTIONS:
  --screen <screen>       Values: all, main, <index> (default: all)

$ wallpaper set --help

OVERVIEW: Set image as wallpaper.

USAGE: wallpaper set <path> [--screen <screen>] [--scale <scale>] [--fill-color <fill-color>]

ARGUMENTS:
  <path>                  The path to the image to use as wallpaper.

OPTIONS:
  --screen <screen>       Values: all, main, <index> (default: all)
  --scale <scale>         Values: auto, fill, fit, stretch, center (default: auto)
  --fill-color <fill-color>
                          Format: Hex color <RRGGBB>

$ wallpaper set-solid-color --help

OVERVIEW: Set solid color as wallpaper.

USAGE: wallpaper set-solid-color <color> [--screen <screen>]

ARGUMENTS:
  <color>                 The color to use as wallpaper.

OPTIONS:
  --screen <screen>       Values: all, main, <index> (default: all)

Set

wallpaper set unicorn.jpg

Set solid color

wallpaper set-solid-color 0000ff

Get

wallpaper get
/Users/sindresorhus/unicorn.jpg

API

Building this requires the latest Xcode and macOS version. The package supports macOS 10.14.4 or later.

Install

Add the following to Package.swift:

.package(url: "https://github.com/sindresorhus/macos-wallpaper", from: "2.3.1")

Or add the package in Xcode.

Usage

import Wallpaper

let imageURL = URL(fileURLWithPath: "<path>", isDirectory: false)
try! Wallpaper.set(imageURL, screen: .main, scale: .fill)

let solidColor = NSColor.blue
try! Wallpaper.set(solidColor, screen: .main)

print(try! Wallpaper.get(screen: .main))

See the source for more.

Dev

Run

swift run wallpaper

Build

swift build --configuration=release --arch arm64 --arch x86_64 && mv .build/apple/Products/Release/wallpaper .

Related

• wallpaper - Get or set the desktop wallpaper cross-platform (Uses this binary)
• macos-trash - Move files and directories to the trash
• do-not-disturb - Control the macOS Do Not Disturb feature
• More…

macos-wallpaper's Issues

remote image support

I'd love to be able to download and set a remote desktop image.

wallpaper http://imgur.com/a/DdV4w#VGgJD9O

Multiple spaces

Different "spaces" can have different wallpapers -- currently, only first one is processed.

Invoking multiply with the same path/different file, produces no change

I've written (well, ported) a program that procedurally generates tiled wallpapers (not yet in npm), using the wallpaper module to optionally set it as the desktop background. A straightforward method of use would seem to be to keep invoking it to generate a new background at the same location, and then reset the wallpaper. However, the Mac OS wallpaper CLI tool doesn't allow for this mode of use, as after the first invocation, further invocations after image regenerations have no effect on the desktop background.

To be clear, this is the sort of thing I'm talking about:

let wp = require('wallpaper');
wp.set("output.png");
createNewImageFileAt("output.png");
wp.set("output.png");

Obviously, this is an artifact of the way that setDesktopImageUrl works, and not anything macos-wallpaper is doing per se... but of course users shouldn't have to be bothered with how the underlying mechanisms of the tool (or module) work - it should "just work" according to the most straightforward user expectations.

Not sure the best way to go about this. I assume there's some way to send a message to Dock to reload the wallpaper, but judging from discussion on #13 the right way to do this isn't currently known. Perhaps just flushing the setting to, I dunno, /dev/null, and then to the user-supplied argument? This probably produces an annoying sort of "flash", but it could be mitigated by only doing this if the new argument matches the pre-existing value in the db.

Obviously, my app, and other consumers of the wallpaper npm module, could just do this ourselves, instead of asking macos-wallpaper to fix it; but fixing it in one place instead of working around it in many others seems the more ideal solution.

Another point to consider is consistency across platforms - what do the Windows or Linux implementations of the wallpaper module do when they receive the same path twice (but with different actual image files)? If they behave differently than the Mac OS version, then unification would seem a good idea.

However, if you feel that this change is inappropriate, and that the current behavior should be left as-is, then I'd like to alternatively propose that the documentation be updated (here, in wallpaper-cli, and in the Node wallpaper module) to make this behavior clear.

Thanks!

Cross-fade animation

@sindresorhus thanks for the great library! Not sure if this is possible but any way we could add a cross fade animation to changing wallpapers?

Rewrite in Swift

Would make it easier to maintain. Should use a good Swift CLI argument parsing library.

Pull request welcome :)

Support Spaces

I have seven spaces defined on my main monitor, and only one path is returned (currently returning the path for the wallpaper on the third space). Would be great if paths for wallpapers on all Spaces was returned!

Possibly related to #25?

Unable to change wallpaper for second time in Sonoma

MacOS version: Sonoma 14.2.1
macos-wallpaper version: 2.3.1
Mac: mac studio with m2max

Situation:

When I use the command line to execute

wallpaper set 'path/to/picture.jpg'

It works fine for the first time, but when I replace another picture and run the above command again, the wallpaper will not be updated.
Observing the MacOS system settings -> wallpaper, I saw that after executing the command line, the pictures inside were updated, but my wallpaper was not updated. Desktop wallpaper only updates when I switch fill mode.

Set wallpaper stretch setting

I would like to be able to manually set the wallpaper stretch to "Stretch to Fill Screen" via this package. I don't know objective-c enough to update this myself, but if someone could that would be awesome.

Thanks.

discussion: canvas?

Hi sindresorhus,

Sorry for opening an issue, but a friend and I were discussing whether or not it'd be possible to render/use HTML5 Canvas elements as wallpapers.

Since you've dug around cross-platform wallpaper APIs & the discussion is mostly on-topic, I figure I'd ask.

Thanks!

Every color is... #5372A4

When I try to use the set-solid-color option to change the solid background color, the color is always set to #5372A4 (no matter which hex code I choose) 🙂 Weird.

wallpaper set-solid-color ff0000

Tested on macOS <W14.1.2 (23B92).

Multiple monitor support

Currently it'll only report back the "primary" monitor wallpaper:

forScreen:[NSScreen mainScreen]

---

Not that's it's super important, but just wanted to bring it up 😉

MacOS Mojave

Hey there!

I wanted to ask if you are going to support macOS Mojave?
It might be quite tricky because of .heic files being the format for dynamic desktop wallpapers.

Setting background color

Hello,
Thanks for making this!
I need to show background images in the center and if they are small enough the solid color blue background shows behind them.

Is there a way to set a color as well? (probably requires setting NSWorkspaceDesktopImageFillColorKey )

Thanks!

Support `tile` mode

This is a nice little utility. However, I can't fully use it because I like to use tiled graphics for my desktop picture. (Or whatever the correct name for it is---it's what System Preferences.app presents as "Tile").

Is there a way to add tile to the list of [scale] choices?

Sonoma support

I'm guessing an internal macOS API changed in 14.0 or something because this was working fine for me (v2.3.1) before I upgraded to Sonoma:

$ wallpaper set-solid-color 001729

Now regardless of the color code I provide, the color changes from whatever it is to some shade of blue which I'm guessing is a default.

Case if the wallpaper is set to change every X minutes.

If I set my Desktop wallpaper settings to:

• Change picture: Every X minutes
• Random Order

this binary only gives me a path to the folder instead of the currently active file:

➔  ./wallpaper
/Users/musically_ut/Pictures

---

I had to resort to some hackery to get the actual active wallpaper: musically-ut/WhichBG. However, I don't know how to map the correct wallpaper to the correct screen/desktop in that setting.

Disable automatic changing of wallpaper image

When I set my wallpaper using wallpaper to a directory instead of an image (e.g. wallpaper set ~/.trunk/wallpaper/desktop), it automatically checks the "Change picture every X minutes" checkbox. This does not happen when I set the wallpaper to a specific file (e.g. wallpaper set ~/.trunk/wallpaper/desktop/foggy-trees.jpg). Is this an Apple-imposed limitation? Or could there be a CLI flag that allows me to disable that functionality?

Try it on OS X 10.6

Any help?

Unable to build as part of Xcode Project

For reasons that I don't quite comprehend, adding this package to any Xcode project results in a "Missing required module 'SQLiteObjc" error.

I am very new to Swift but am fairly certain that I have imported all of the required frameworks correctly. This had initially been working but since rebuilding my project due to an Xcode crash, I have been unable to replicate my earlier success. I have tried re-creating the project on other machines, which yields the same error.

Thus far, I have tried:

• Generated Xcode project for Wallpaper via "swift package generate-xcodeproj --xcconfig-overrides=Config.xcconfig".
• Added Wallpaper project to main Xcode project and linked all four libraries to the target.
• Added Wallpaper frameworks directly to main project folder and linked.
• Switched to Swift 4.2.0.
• Switched to Xcode 10.0.

Attached are screenshots of my current project configuration.

Sonoma Not Returning correct image with get

Prior to Sonoma it was working fine, now it returns the same incorrect image for all (3) my connected screens. My images cycle very 5 minutes and after a cycle, it still returns the 3 same incorrect images.

Is it possible to use this feature in a macOS app?

Is it possible to use this library in a macOS app built on Appkit/SwiftUI?

Usecase: Able to change the wallpaper of macOS from mac app.

Thank you

10.14/mojave: set only works on the current desktop

Expected: wallpaper set Sierra.jpg should set the desktop everywhere.
Observed: The command only sets the current desktop's background image.

Support Mojave dynamic wallpapers

Probably not going to be easy.

Multiple spaces support

It could be great to work on every desktop. :)

Setting wallpaper via "run shell script" step in shortcuts app does not work

When I try to run the /opt/homebrew/bin/wallpaper set "..." command in a "run shell script" step of a shortcut, nothing happens. It does not give an error, but the wallpaper does not change. How can I get this working?

When installing via MDM (Jamf)...

Hi, love the tool! When installing via Jamf (Cloud) I made a package to install the binary, install the pics folder (in Application Support) and then a post install to run it.
It often comes back with a "can't locate the folder.name" with the pics.
If I wait a while and run the script, it works. So I added a sleep to pause before that line below:
`wallpaper set "/Library/Application Support/Wallpaper"

It does help, but not 100%. I have a followup policy to run the above line and that seems to pickup those that didn't work on the install...
Anything I'm missing?

Cheers,
Scott

'get' command returns the same wallpaper for different screens with different wallpapers.

This is on Mojave. It reports the same wallpaper across both screens, but only the first screen has the reported wallpaper.

There is a $60.00 open bounty on this issue. Add more on Issuehunt.

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on Issuehunt to raise funds.

Does not work in OS X 10.12 Sierra

I was looking for an easy way to change the wallpaper via terminal and this seemed like a solution until it did not work. At first I was using AppleScript which works but only in the AppleScript editor

so far the best solution I found was this

function wallpaper() { sqlite3 ~/Library/Application\ Support/Dock/desktoppicture.db "update data set value = '$1'" && killall Dock }Here

Support for cocoapods

Is there a reason why the lib is not published as pod package? By the way a useful library 👍

Support setting a solid color

I like using solid colors cause I've customized my desktop with text widgets. Would be nice if I could use this tool to set it from my script that I run when setting up a new Mac 🤓

Update: I just looked into this and only found https://developer.apple.com/documentation/appkit/nsworkspace/desktopimageoptionkey/1535407-fillcolor, but not sure if it’s possible to set this without an image url.

---

IssueHunt Summary

medusalix has been rewarded.

Backers (Total: $60.00)

• issuehunt ($60.00)

Submitted pull Requests

• #30 Add set-solid-color command

---

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.

App Quit Unexpectedly after trying to set a wallpaper

Here is the error message I get and my app quits immediately:
Fatal error: 'try!' expression unexpectedly raised an error: unable to open database file (code: 14) Lost connection to device

Here is my code to set the wallpaper:
let path = (call.arguments as! Dictionary<String, AnyObject>)["path"] as! String; let scale = (call.arguments as! Dictionary<String, AnyObject>)["scale"] as! String; print("switft wallpaper path: ", path) let imageURL = URL(fileURLWithPath: path, isDirectory: false) try! Wallpaper.set(imageURL, screen: .all, scale: Wallpaper.Scale(rawValue: scale) ?? .auto)

Here is the full error when I run it from xcode:
switft wallpaper path: /Users/jeff/Library/Containers/com.AppName.co/Data/Wallpapers/yyuvw2q4ptpoatl.jpg 2023-07-11 15:49:36.137925+0100 AppName[17643:174990] [logging-persist] cannot open file at line 46846 of [554764a6e7] 2023-07-11 15:49:36.137996+0100 AppName[17643:174990] [logging-persist] os_unix.c:46847: (0) open(/Users/jeff/Library/Containers/com.AppName.co/Data/Library/Application Support/Dock/desktoppicture.db) - Undefined error: 0 AppName/MainFlutterWindow.swift:64: Fatal error: 'try!' expression unexpectedly raised an error: unable to open database file (code: 14) 2023-07-11 15:49:36.139022+0100 xxx[17643:174990] AppName/MainFlutterWindow.swift:64: Fatal error: 'try!' expression unexpectedly raised an error: unable to open database file (code: 14)

What I fins strange is that this file Dock/desktoppicture.db doesn't exits in this location /Users/jeff/Library/Containers/com.AppName.co/Data/Library/Application Support/Dock/desktoppicture.db
but before I changed my app package_name the file could be found in the previous app directory folder location.

Will appreciate any assistance with this issue
Thanks,
Jeffrey.

Error using 'wallpaper get --screen'

When trying to view the current wallpaper settings, I am getting an error when specifying a screen.

# wallpaper --version
2.3.0

# wallpaper get

/Users/sxdjt/shared/wallpaper/geneva-station.jpg
/Users/sxdjt/shared/wallpaper/2001-bw.jpg

# wallpaper screens

0 - iMac
1 - BenQ EL2870U

# wallpaper get --screen 0

Error: The value '0' is invalid for '--screen <screen>'
Help:  --screen <screen>  Values: all, main, <index>
Usage: wallpaper get [--screen <screen>]
  See 'wallpaper get --help' for more information.

# wallpaper get --screen 1

Error: The value '1' is invalid for '--screen <screen>'
Help:  --screen <screen>  Values: all, main, <index>
Usage: wallpaper get [--screen <screen>]
  See 'wallpaper get --help' for more information.

# wallpaper get --screen main

/Users/sxdjt/shared/wallpaper/geneva-station.jpg

Running MacOS 12.1.

Switch from `SwiftCLI` to `swift-argument-parser`

https://github.com/apple/swift-argument-parser

OS 10.15.1 Catalina EACCES error

Thank you for open source this project, it's a great job for me.
It used to work util I updated my mac
But i find it didn't work today and throw this error
Looking forward to your answer, thank u.

Error: spawn /Users/blacker/wallpaper/source/macos-wallpaper EACCES