macos-wallpaper: a small Swift package and CLI for the macOS desktop picture

Both a command and a library, with the same surface

macos-wallpaper is described as a command line app and a Swift package at the same time, and the distinction is not marketing: the package is the implementation and the binary is a thin wrapper over it.

The headline behaviour is narrow and specific. The tool correctly handles getting the active wallpaper even when the wallpaper is set to a directory, which is the case that trips up most attempts to read the desktop picture from a script. macOS lets you point the desktop picture at a folder, and the system then picks an image from it according to the current display, so asking the wrong question returns nothing useful.

The command interface has four subcommands. There is get for the current wallpaper images, set for an image file, set-solid-color for a colour, and screens to list the available screens. The screen selector takes all, main, or an index, and the default is all, so the plain invocation applies to every display rather than only the main one.

The usage block is short enough to be worth reading in full:

$ wallpaper

USAGE: wallpaper <subcommand>

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.

The set subcommand adds two options beyond the screen selector. The scale option takes auto, fill, fit, stretch or center, with auto as the default, and a fill colour option that takes a hex colour in RRGGBB form, which is the colour used to fill the areas not covered when the image is scaled to fit rather than stretched.

Tiling is the feature macOS took away

The note in the documentation about tiling is the most interesting thing in the readme, because it explains a limitation rather than hiding it.

macOS still offers a Tile option in System Settings, but it has no API. The undocumented NSWorkspace placement key silently ignores tile values, and the old desktoppicture.db method no longer works on macOS 26 and later. The consequence is that the scale option does not support tile, and if you need it you have to set it manually in System Settings.

That is two separate dead ends in one sentence. The first is the old approach, which worked by reading and writing a database of desktop picture records, and it has stopped working on recent macOS. The second is the current approach, where the placement is set through a key that is not officially documented and which does not honour the tile value.

So a tool that claims to manage the wallpaper fully has to concede one part of the system settings panel, and it says so plainly rather than silently producing a wallpaper in the wrong arrangement.

The same honesty shows up in the sandboxing note. In sandboxed apps, the library gracefully handles database access restrictions and may return directory paths instead of specific image files when getting the current wallpaper. The tool therefore returns something usable in a sandbox, but the result is a directory rather than the image that is actually on screen, and the caller has to know that.

Both notes describe the same engineering position: the underlying system APIs are partly private and partly removed, so the tool works around what it can and documents what it cannot.

Installing the command with Homebrew or from a release

The command line app requires macOS 10.14.4 or later, which is stated separately from the package requirement because the floor comes from the system APIs rather than from the tool.

Installation through Homebrew is one command:

brew install wallpaper

The manual route is to download the binary from the releases page and put it in /usr/local/bin.

For the Swift package, the dependency is declared in Package.swift:

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

The version floor in the dependency is 2.3.2, which is also the third most recent release in the list. Building the package requires the latest Xcode and macOS version, and the package supports macOS 10.14.4 or later.

The library usage is deliberately terse. A URL is built with the file path initializer, the set call takes an optional screen and scale, a solid colour uses the same set function with an NSColor, and get returns the current path:

import Wallpaper

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

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

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

The module is imported as Wallpaper, not as macos-wallpaper, and the enumeration cases are .main for a screen and .fill for a scale, so the API reads as a small API rather than a wrapper around one. The source of the Wallpaper.swift file is pointed to for the rest.

A cross-platform wrapper sits on top of this binary

The related projects list contains the entry that explains the shape of the ecosystem around this tool.

There is a separate wallpaper project, described as getting or setting the desktop wallpaper cross-platform, and the note says it uses this binary. So macos-wallpaper is the macOS implementation, and the cross-platform tool drives it as a subprocess on macOS while doing something else elsewhere.

That arrangement tells you something about the design pressure. On macOS there is no public API for setting the desktop picture, so the practical route is a small native helper that uses the private or semi-private mechanisms, and a cross-platform tool that shells out to it. This repository is the helper, and its interface is a command line with a get and a set, which is exactly the shape a subprocess wrapper needs.

The other related projects follow the same pattern of small, single-purpose macOS utilities, a tool to move files and directories to the trash and one to control the Do Not Disturb feature.

The repository layout is correspondingly small. There is Package.swift, a Package.resolved, a Sources directory, a readme, a license file, an .editorconfig and .gitattributes, and two fixture images, fixture.jpg and fixture2.jpg, which are almost certainly there for the test suite rather than for you.

The command interface itself is worth noting for scripting. Setting an image and setting a colour are both one-liners:

wallpaper set unicorn.jpg

wallpaper set-solid-color 0000ff

and reading the current wallpaper prints an absolute path, which is the input another script would need.

A small tool with a long tail of releases

The maintenance picture for a project of this size is worth stating carefully, because the release dates are spread out.

The three most recent releases are v2.3.4 from 2026-04-19, v2.3.3 from 2025-10-02 and v2.3.2 from 2024-09-16. The repository is not archived, the default branch is main, and the last push was on 2026-09-20, about a month before the current date.

So the code is being worked on, the releases are not frequent, and the gap between them has been widening rather than narrowing. v2.3.2 to v2.3.3 is about a year, v2.3.3 to v2.3.4 is about six months. For a tool whose entire job is a thin wrapper over system APIs, that pace is defensible, since there is not much to change and the risk is in macOS releases rather than in demand for features.

The macOS 26 note in the tiling section is the interesting part of that. The old desktop picture database method stopped working on macOS 26, and the fix in the release line around it presumably addressed that. This is a class of software where the platform moves under you, and the maintainer has to update it when Apple changes something, so the release rate tracks Apple's cadence rather than the feature backlog.

The licence is MIT, with a license file at the root of the repository. For anyone building on top of it, that is the simplest possible answer to the licensing question.

The practical takeaway for an adopter is to pin a version rather than track the branch, since the release line moves in steps and a macOS update is what triggers a new one.

Editorial conclusion

macos-wallpaper suits a macOS developer who needs wallpaper changes from a script, a build pipeline or another app, and who wants a dependency free Swift package rather than a shell workaround. It does not suit a Linux or Windows user, it does not support tiling, and it is a single author project with releases spaced over years. Before adopting it, note that setting a wallpaper requires macOS 10.14.4 or later, that the tile option must be set by hand in System Settings because the old database method no longer works on macOS 26, and that sandboxed apps may get a directory path back instead of an image file.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. sindresorhus/macos-wallpaper on GitHub