The wallpaper package sets a desktop background, with different options per operating system

A two function module with an options object per platform

The wallpaper package gets or sets the desktop wallpaper, and it works on macOS 10.14.4 and later, on Linux, and on Windows 10 and later. The whole API is two calls:

import {getWallpaper, setWallpaper} from 'wallpaper';

await setWallpaper('unicorn.jpg');

await getWallpaper();
//=> '/Users/sindresorhus/unicorn.jpg'

getWallpaper takes an optional options object and returns a promise for the path of the current desktop wallpaper. setWallpaper takes the image path and an optional options object and returns a promise.

The installation is a single npm install, and the module is a modern ES module with a single export, side effects declared false, and a Node engine requirement of 16 or newer. There are no runtime dependencies in the manifest, which is worth noting when you look at what it has to do: the readme's related section points to the macos-wallpaper and windows-wallpaper packages, described as the macOS binary used in this module and the Windows binary used in this module, so the platform work is done by shipping small platform binaries rather than by depending on a large cross platform library.

The audience is a developer who wants to script a wallpaper change, and the practical use cases are the ones the related packages suggest: a wallpaper-cli for the command line, and the module itself for use inside a Node application.

Every option means something different on each platform

The options are the interesting part of this module, because the same option name has different semantics depending on the operating system.

The screen option exists on macOS only. Its values are 'all', 'main', or the index of a screen from the screens() call, and the default differs between the two functions: getWallpaper defaults to 'main', while setWallpaper defaults to 'all'. If you set 'all' on the get side, the function returns a promise for an array of strings rather than a single path.

The scale option applies to macOS and Windows, and the allowed values differ. On macOS they are 'auto', 'fill', 'fit', 'stretch' and 'center', with a default of 'auto'. On Windows they are 'center', 'stretch', 'tile', 'span' and 'fit', with a default of 'span'. On Linux the option is ignored.

And the screen option is hard-coded to 'main' on Linux and on Windows, which the documentation states directly. So on a two monitor Linux setup, asking for all screens does nothing.

The behaviour of the set side on macOS has one more wrinkle worth knowing before you rely on it. On macOS it sets the wallpaper on the active space, and there is no way to set it on all spaces. That is a property of how macOS spaces work rather than a limitation the package could code around, and it means a script that switches spaces afterwards will find the old background.

For a user, the practical summary is that the module's behaviour is macOS first, Windows second, and Linux last, and that the defaults are chosen so the common single screen case works everywhere while the advanced cases are macOS only.

Solid colour and screen enumeration are macOS only

Two more functions round out the API, and both are marked as macOS only in the documentation.

setSolidColorWallpaper takes a colour and an optional options object, and returns a promise. The colour is a RGB hex value without the hash sign, for example 000000 for black, and the screen option behaves the same way as elsewhere, with 'all' as the default. The usage is a single import and call:

import {setSolidColorWallpaper} from 'wallpaper';

await setSolidColorWallpaper('000000');

The screens function returns a promise for an array of the available screen names, and the example output shows a display name rather than an index:

import {screens} from 'wallpaper';

await screens();
//=> ['Color LCD']

Those screen names are what the index form of the screen option refers to, so on a multi display macOS setup you can name a specific screen rather than relying on the order the system reports.

The fact that both of these are macOS only is not a gap that can be closed easily, since the underlying concepts differ: a solid colour wallpaper is a macOS setting with no direct equivalent on the other two platforms, and screen enumeration on Windows and Linux is exposed through different, non standard mechanisms. The module reflects that rather than pretending the platforms are the same.

The Linux half of the code is looking for an owner

There is one line at the top of the readme that matters more than any of the API details, and it is a request rather than a feature: a maintainer is needed for the Linux part of the code, and no new Linux related changes will be accepted until someone with good Linux knowledge volunteers.

That is an unusual thing to find in the readme of a popular package, and it is a statement about the shape of the project rather than a passing comment. The maintainer of this module is well known for a large body of small, sharp Node utilities, and the Linux implementation of wallpaper is the part that needs knowledge of how each desktop environment sets its background, which is a different problem on every distribution and desktop environment combination. A pull request that guesses at the mechanism is more likely to be wrong than right, so the project is asking for someone who knows rather than accepting drive by changes.

For a user, this changes how the module should be read. On macOS and Windows, the platform behaviour is defined and tested. On Linux, the option surface is deliberately narrow, with the scale option ignored and the screen hard-coded, which is consistent with an implementation that does the safe thing rather than guessing. The repository does carry a source directory and test files, and the test script runs three tools in sequence, the linter, the test runner and the type definition tests, and the test runner is configured to run serially, which makes sense for a module that changes global desktop state.

The practical advice is simple. If you are on macOS or Windows, the module is a well specified tool. If you are on Linux, read the maintainer request before filing an issue about a missing option, because the answer is probably that nobody with the right knowledge is maintaining that code right now.

Dynamic wallpapers are explicitly out of scope

The FAQ answers two questions that any user will ask, and the answers are precise about what this module does not do.

The first is how to set a website as a static wallpaper. If you only need a static snapshot, the documentation suggests a separate capture tool and then passing the result to this package, and it notes that you can make it semi dynamic by capturing the snapshot every ten seconds, for example. So the composition is available even though the feature is not.

The second is how to set a website, a video, or WebGL as a dynamic wallpaper, and the answer begins with the sentence that you cannot use this package to set a dynamic wallpaper. The alternatives are named per platform. On macOS, Plash, which lets you set any website as your wallpaper, where the website could contain a fullscreen video, WebGL, a slideshow, something animated. The documentation also points out that you can do the same thing with Electron on macOS and Linux by creating a browser window of the desktop type. On Windows, it points to Wallpaper Engine, which is available on Steam, HumbleBundle and Green Man Gaming for around 4 US dollars.

That separation is the right one. A Node module that shells out to a small platform binary can set a static image, and that is a well defined operation. A dynamic wallpaper needs a compositor, a video pipeline or a browser engine, and pretending a wallpaper setter can do that would be a much larger and much more fragile package.

For anyone scripting a wallpaper change on a build server, the answer is also the simplest one in the FAQ: use a static image, and if you need something dynamic, use a tool built for it.

Maintenance, tooling and the shape of the package

The release history is short and recent. The tags are v7.2.1 on 2024-03-18, v7.3.0 on 2026-03-11 and v7.3.1 on 2026-04-19, and the manifest version is 7.3.1. The last push was on 2026-09-20 and the repository is not archived, so the package is in active use, with the caveat about the Linux implementation noted above.

The tooling tells you the standards the code is held to. The test script runs xo for linting, ava for the tests and tsd for the type definitions, so the declarations are checked against the implementation rather than being maintained by hand. The test runner is configured to run serially, which is the correct choice for a module that mutates global desktop state, since parallel tests would each try to set the wallpaper of the same machine. The manifest also has a files array listing the entry point, the declarations and the source directory, and a keywords list that covers the platforms and the domain.

The repository is correspondingly small, with the entry point, the type declarations and their type tests, a source directory, a test file, and two fixture images used by the tests, since setting a wallpaper needs something to set. There is also a licence file and an .npmrc, and the package is a module with no CommonJS build, which is a decision that costs compatibility with older tooling and buys the simpler entry point and the side effects guarantee.

For a user, the interesting question is not the internals but the platform matrix, and the answer is in the readme's first three lines: macOS 10.14.4 and later, Linux, and Windows 10 and later, with the Linux caveat to keep in mind.

Editorial conclusion

wallpaper suits a Node script that needs to change a desktop background, for instance a build pipeline that stamps a release screenshot onto a test machine, and it suits macOS users who want the full set of screen and scaling options. It is the wrong choice if you want a dynamic wallpaper, because the package explicitly cannot set one and the documentation points to other tools, and a poor match if you are on Linux and need per monitor behaviour, because the screen option is hard-coded there and the scale option is ignored. Before adopting on Linux, read the maintainer request at the top of the readme, because no new Linux related changes are being accepted until someone volunteers.

Frequently asked questions

Official sources

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