# wallpaper

> Manage the desktop wallpaper

Latest version **7.3.1** (published 2026-04-19) · MIT license · 0 weekly downloads

## Install

```sh
npm install wallpaper
pnpm add wallpaper
yarn add wallpaper
bun add wallpaper
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 7.3.1 |
| Published | 2026-04-19 |
| First published | 2015-04-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=16 |
| Dependencies | 0 |
| Unpacked size | 6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1091 |
| Author | Sindre Sorhus |
| Maintainers | sindresorhus |
| Keywords | macos, linux, windows, wallpaper, desktop, background, image, picture, photo |

## Links

- npm: https://www.npmjs.com/package/wallpaper
- Repository: https://github.com/sindresorhus/wallpaper
- Homepage: https://github.com/sindresorhus/wallpaper#readme
- Issues: https://github.com/sindresorhus/wallpaper/issues
- Funding: https://github.com/sponsors/sindresorhus
- npm.io page: https://npm.io/package/wallpaper

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 7.3.1 (latest) — 2026-04-19
- 7.3.0 — 2026-03-11
- 7.2.1 — 2024-03-18
- 7.2.0 — 2023-10-29
- 7.1.0 — 2023-10-14
- 7.0.0 — 2023-06-23
- 6.1.1 — 2022-01-23
- 6.1.0 — 2022-01-10
- 6.0.0 — 2021-11-22
- 5.0.1 — 2021-06-08
- 5.0.0 — 2021-05-27
- 4.4.2 — 2020-11-25
- 4.4.1 — 2019-06-15
- 4.4.0 — 2019-03-31
- 4.3.0 — 2019-03-11
- … 14 more at https://npm.io/package/wallpaper/versions

## README

# wallpaper

> Get or set the desktop wallpaper

Works on macOS 10.14.4+, Linux, and Windows 10+.

*Maintainer needed for the Linux part of the code. No new Linux-related changes will be accepted until someone with good Linux knowledge volunteers.*

## Install

```sh
npm install wallpaper
```

## Usage

```js
import {getWallpaper, setWallpaper} from 'wallpaper';

await setWallpaper('unicorn.jpg');

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

## API

### getWallpaper(options?)

Returns a `Promise<string>` with the path of the current desktop wallpaper.

#### options

Type: `object`

##### screen *(macOS only)*

Type: `string | number`\
Values: `'all'`, `'main'`, or the index of a screen from `.screens()`\
Default: `'main'`

The screen to get the wallpaper from.

If you set `'all'` then `getWallpaper()` will return a `Promise<string[]>`.

### setWallpaper(imagePath, options?)

Returns a `Promise`.

On macOS, it sets the wallpaper on the active space. There is no way to set it on all spaces.

#### imagePath

Type: `string`

The path to the image to set as the desktop wallpaper.

#### options

Type: `object`

##### screen *(macOS only)*

Type: `string | number`\
Values: `'all'`, `'main'`, or the index of a screen from `.screens()`
Default: `'all'`

The screen to set the wallpaper on.

*On Linux and Windows it's hard-coded to `'main'`.*

##### scale *(macOS & Windows)*

Type: `string`\
macOS Values: `'auto' | 'fill' | 'fit' | 'stretch' | 'center'`\
Windows Values: `'center' | 'stretch' | 'tile' | 'span' | 'fit' | 'fill'`\
Default macOS: `'auto'`\
Default Windows: `'span'`

Scaling method.

### setSolidColorWallpaper(color, options?) *(macOS only)*

Returns a `Promise`.

#### color

Type: `string`

The color to set as a RGB Hex value. For example, `000000` for black.

#### options

Type: `object`

##### screen

Type: `string | number`\
Values: `'all'`, `'main'`, or the index of a screen from `.screens()`
Default: `'all'`

The screen to set the wallpaper on.

```js
import {setSolidColorWallpaper} from 'wallpaper';

await setSolidColorWallpaper('000000');
```

### screens() *(macOS only)*

Returns a `Promise<string[]>` with the available screens.

```js
import {screens} from 'wallpaper';

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

## FAQ

#### How can I set a website as a static wallpaper?

If you only need a static snapshot of the website, you can use [`capture-website`](https://github.com/sindresorhus/capture-website) and then pass the result to this package. You can make it semi-dynamic, by capturing the website snapshot every 10 seconds, for example.

#### How can I set a website, video, or WebGL as a dynamic wallpaper?

You cannot use this package to set a dynamic wallpaper.

On macOS, check out [Plash](https://github.com/sindresorhus/Plash), which lets you set any website as your wallpaper. The website could contain a fullscreen video, WebGL, slideshow, animated, etc.

You can also do this with Electron on macOS and Linux by using [`new BrowserWindow({type: 'desktop'})`](https://www.electronjs.org/docs/latest/api/browser-window#new-browserwindowoptions).

On Windows, you can use [Wallpaper Engine](https://wallpaperengine.io). It's available on Steam, HumbleBundle, and Green Man Gaming for around 4 USD.

## Related

- [wallpaper-cli](https://github.com/sindresorhus/wallpaper-cli) - CLI for this module
- [macos-wallpaper](https://github.com/sindresorhus/macos-wallpaper) - macOS binary used in this module
- [windows-wallpaper](https://github.com/sindresorhus/windows-wallpaper) - Windows binary used in this module
- [trash](https://github.com/sindresorhus/trash) - Move files and directories to the trash

---
_Source: https://npm.io/package/wallpaper · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._