Manage the desktop wallpaper

Overview

wallpaper

Get or set the desktop wallpaper

Works on macOS 10.12+, 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

$ npm install wallpaper

Usage

const wallpaper = require('wallpaper');

(async () => {
	await wallpaper.set('unicorn.jpg');

	await wallpaper.get();
	//=> '/Users/sindresorhus/unicorn.jpg'
})();

API

.get(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 .get() will return a Promise<string[]>.

.set(imagePath, options?)

Returns a Promise.

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 only)

Type: string
Values: 'auto' | 'fill' | 'fit' | 'stretch' | 'center'
Default: 'auto'

Scaling method.

.screens() (macOS only)

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

(async () => {
	await wallpaper.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 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, 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'}).

On Windows, you can use Wallpaper Engine. It's available on Steam, HumbleBundle, and Green Man Gaming for around 4 USD.

Related

Comments
  • Linux improvements

    Linux improvements

    • [ ] GNOME 2 support. Currently it targets GNOME 3. Should be pretty easy to support GNOME 2. Just detect the version and fall back. See: http://askubuntu.com/questions/66914/how-to-change-desktop-background-from-command-line-in-unity
    • [ ] KDE4 support. http://blog.zx2c4.com/699 https://code.google.com/p/ksetwallpaper/ https://gist.github.com/X4/5197205
    • [x] Cinnamon support.
    enhancement help wanted 
    opened by sindresorhus 11
  • Example Error

    Example Error

    Running your example:

    const wallpaper = require('wallpaper');
    
    wallpaper.set('unicorn.jpg').then(() => {
        console.log('done');
    });
    
    wallpaper.get().then(imagePath => {
        console.log(imagePath);
        //=> '/Users/sindresorhus/unicorn.jpg'
    });
    

    On Linux Ubuntu throws an error on /lib/linux.js:

    return cp.execFile(app.cmd, app.get).then(stdout => 
    
    TypeError: Cannot read property 'cmd' of undefined
    

    Seems to be due to using async functions (get and set) at the same time (same problem with different error if using get before set

    The problem solves simply using the second command inside the callback:

    const wallpaper = require('wallpaper');
    
    wallpaper.set('unicorn.jpg').then(() => {
        console.log('done');
        wallpaper.get().then(imagePath => {
            console.log(imagePath);
            //=> '/Users/sindresorhus/unicorn.jpg'
        });
    });
    

    I'm not sure if the problem is just in linux, and if its an error in the example code or in the linux library.

    opened by angrykoala 8
  • set wallpaper doesn't work

    set wallpaper doesn't work

    My script looks like this:

    wallpaper.set(fullImagePath).then(() => {
      console.log('Set as wallpaper')
      wallpaper.get().then(imagePath => {
           console.log(`Current wallpaper: ${imagePath}`)
      })
    })
    

    which is run by crontab on Ubuntu 16.04 (with GNOME). The wallpaper doesn't change, and the logged imagePath does not equal fullImagePath. The output was like:

    Image already downloaded at: /home/doma/scripts/bing-wallpaper-script/downloads/20170605.jpg
    Set as wallpaper
    Current wallpaper: /usr/share/backgrounds/warty-final-ubuntu.png
    

    However when I run this script manually (not invoke by crontab), it works fine.

    opened by SevenOutman 7
  • Crashes on GNOME

    Crashes on GNOME

    I get this error when I run

    wallpaper.get().then(console.log)
    

    Error:

    UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error: Command failed: gsettings get org.cinnamon.desktop.background picture-uri
    No such schema 'org.cinnamon.desktop.background'
    

    First I thought it was a bug on my fork, so I tried pulling from your repo, and then I tried installing the package from npm again. Same problem, my guess is that the command for Cinnamon somehow replaces the command for GNOME (probably because they both use gsettings).

    opened by fa7ad 7
  • Add suppport for KDE/Plasma

    Add suppport for KDE/Plasma

    On my linux system with Plasma (running Arch Linux/Manjaro) this tool does not work since neither gsettings nor gconftool-2 nor dcop work even though they are present.

    This PR adds a working method using qdbus.

    Without #27 or similar this does not really help as the other ones (gsettings ...) are present and used first. As a workaround I just manually delete all other services from the lib/linux.js script for now.

    opened by maxanier 6
  • Gnome caching

    Gnome caching

    Hi. I was using your package and suddenly it seemed to have stopped working, it's not really a bug though (Linux).

    I am using elementaryOS (Ubuntu) and gsettings set picture-uri seems to be caching wallpapers/paths and does not update the wallpaper if a same path is used (I was changing wallpapers every x seconds with the same name in one folder). It doesn't fail, and doesn't give any errors, I'm not too certain how well-known this knowledge is but maybe it is worth mentioning in a readme section? Once you know this it's easy enough to generate random names.

    Alternative, something like clearing cache might work? But, this isn't best practice I guess?

    Edit^: cache is maybe a bit a wrong explanation/terminology. The path image-uri gets set but wallpaper (when same path) does not update until reboot.

    Or, maybe something like wallpaper.set => "get > set > get > if is the same give warning". Although, it might not be the package it's responsibly.

    Thanks for all your work!

    bug help wanted 
    opened by ghost 6
  • Promisify linux

    Promisify linux

    I promisified linux.js. Did some major refactoring work and wasn't able to test so there might be some flaws in it. It's also getting late here so an upfront sorry for some things I overlooked :).

    opened by SamVerschueren 6
  • Rewrite the Linux part

    Rewrite the Linux part

    This PR is in response of issue #42

    I purpose you a new file organization for manage the multiple background manager on Linux. I'm using nitrogen so for me it is working. It would be cool if some people could test before merge.

    What is it changed ?

    setAvailableApps iterate over all manager and test if they are available, if it is they are stored set method just call the set method of each available background managers get method is more difficult to write, due to multiple managers. I use a strategy consisting of count the apparition of a file, and the most used will be return.

    The final point is personnal, I think it is the more discutable. I'm ok to debate on this point. I hope this work can help.

    Thanks for reading.

    opened by deather 5
  • Cant set wallpaper from url

    Cant set wallpaper from url

    i want to set wallpaper from a url like wallpaper.set("ImAgeurl.jpg").then(() => { }); but it dosent work and desktop wallpaper goes black

    opened by TronIsHere 5
  • Failed to set the desktop wallpaper

    Failed to set the desktop wallpaper

    UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error: Command failed: E:\new Object\node\small\getpic\[email protected]@wallpaper\lib\win-wallpaper.exe E:\new Object\node\small\getpic\RoyalAlcazars_EN-AU13378849776.png

    this is the error message. i have the picture

    opened by huaibaomengxiang 5
  • I am having an issue when i set the wallpaper from electron app

    I am having an issue when i set the wallpaper from electron app

    UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error: Command failed: D:\ionic\demos\electron\electron-tutorial\node_mo dules\wallpaper\lib\win-wallpaper.exe D:\ionic\demos\electron\electron-tutorial\google.png Failed to set the desktop wallpaper (node:2432) DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js proces s with a non-zero exit code.

    I have the google.png image in my path but it's still not setting the wallpaper but generating an error.

    opened by ravisojitra 5
  • Ubuntu 22.04 (Gnome 42) not working anymore

    Ubuntu 22.04 (Gnome 42) not working anymore

    Hi,

    I'm using Ubuntu Jammy with Gnome 42 and the service is not working anymore when gnome set to darkMode. It seems the nes gsetting command is gsettings set org.gnome.desktop.background picture-uri-dark {filename}

    opened by T00rk 2
  • spawn (hardcoded)/macos-wallpaper ENOENT

    spawn (hardcoded)/macos-wallpaper ENOENT

    Hello, using

    • electron (17.1.2) and
    • wallpaper (6.1.1)

    When building dist with electron builder and running the app - the path to macos-wallpaper is for some reason hardcoded to the path of the local project of the device on which it was building.

    The problem is the same with asar false and I tried to manually include wallpaper lib in dist and reference it in the project - it works locally but not after the build again.

    I didn't even notice this before trying to run the app on another device where there is no locally saved dev directory with macos-wallpaper lib in the same place.

    import { screens } from "wallpaper";
    // ...
    const currentMonitors = await screens();
    

    Sentry error after running the build

    Error
    spawn /Users/bumtomica/Development/splashy-desktop/dist/wallpaper/source/macos-wallpaper ENOENT
    // or
    spawn /Users/bumtomica/Development/splashy-desktop/node_modules/wallpaper/source/macos-wallpaper ENOENT
    

    Not sure if I'm doing something wrong with init or build, please advise.

    opened by bumTomica 2
  • If I set the wallpaper twice in a row with the same image, it removes the wallpaper the second time

    If I set the wallpaper twice in a row with the same image, it removes the wallpaper the second time

    If I set the wallpaper twice, the second time it will remove the wallpaper and set it to the default desktop wallpaper. The issue is, I can't rely on get to tell me that the wallpaper is correctly set. When the wallpaper is changed back to default, get still returns the wallpaper I set initially. In fact, on MacOS settings, it still shows the correct wallpaper. My program is setting the wallpaper every 24 hours, but it has to be able to reliably recover from a crash, waking from sleep, and timezone shifts. So what I want to do is be able to check if the wallpaper that is currently set is the correct one, and if not, change it. However, because I can't rely on get to do that, I'm not sure what to do.

    Am I doing something wrong here? I've tried this on multiple computers and am running into this issue consistently. Maybe there's a good way to work around this limitation?

    This is what it looks like if you're running it from the CLI:

    // Set the wallpaper
    $ /macos-wallpaper set ~/Pictures/wallpaper.jpg --screen all --scale auto
    // Wallpaper gets set to this image
    
    // Get the wallpaper
    $ /macos-wallpaper get
    // Correct image is returned
    /wallpaper.jpg
    
    // Run a second set
    $ /macos-wallpaper set ~/Pictures/wallpaper.jpg --screen all --scale auto
    // Wallpaper now becomes default desktop
    
    // Get the wallpaper again
    $ /macos-wallpaper get
    // The image I set earlier is returned, even though the desktop is showing the default wallpaper
    /wallpaper.jpg
    

    Here's a gif that shows the issue: CleanShot 2020-07-14 at 18 48 31

    opened by hisnameisjimmy 6
  • Problems setting wallpaper from cron or as sudo

    Problems setting wallpaper from cron or as sudo

    When invoking simple script that should change wallpaper with sudo ie: sudo /abs/path/script.js or from cron * * * * * /abs/path/script.js wallpaper stays the same. When called manually and without sudo/cron it works as intended.

    Any ideas what might be wrong?

    opened by MDabrowski9LD 5
  • Default wallpaper is shown for ≈0.5 sec

    Default wallpaper is shown for ≈0.5 sec

    Issuehunt badges

    When calling wallpaper.set('img/artwork.png') in a node app running on Mojave, the default wallpaper (not set via this API) is shown for approximately 0.5 sec. Is this a known issue? If so: any ways to get around it? Thanks.

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

    enhancement help wanted :dollar: Funded on Issuehunt 
    opened by daxro 3
Releases(v6.1.1)
  • v6.1.1(Jan 23, 2022)

  • v6.1.0(Jan 10, 2022)

  • v6.0.0(Nov 22, 2021)

    Breaking

    • Require Node.js 12.20 8a5561c
    • This package is now pure ESM. Please read this.
    • Moved from default export to named exports:
      • require('wallpaper').getimport {getWallpaper} from 'wallpaper'
      • require('wallpaper').setimport {setWallpaper} from 'wallpaper'
      • require('wallpaper').setSolidColorimport {setSolidColorWallpaper} from 'wallpaper'
      • require('wallpaper').screensimport {screens} from 'wallpaper'

    https://github.com/sindresorhus/wallpaper/compare/v5.0.1...v6.0.0

    Source code(tar.gz)
    Source code(zip)
  • v5.0.1(Jun 8, 2021)

  • v5.0.0(May 27, 2021)

  • v4.4.2(Nov 25, 2020)

  • v4.4.1(Jun 15, 2019)

    • Fix the .get() method on macOS incorrectly returning all screens as a string e60db7f

    https://github.com/sindresorhus/wallpaper/compare/v4.4.0...v4.4.1

    Source code(tar.gz)
    Source code(zip)
  • v4.4.0(Mar 31, 2019)

    • Refactor TypeScript definition to CommonJS compatible export (#54) 81cc0dc

    https://github.com/sindresorhus/wallpaper/compare/v4.3.0...v4.4.0

    Source code(tar.gz)
    Source code(zip)
  • v4.3.0(Mar 11, 2019)

  • v4.2.0(Jan 9, 2019)

    • Windows: Persist wallpaper change to user's profile https://github.com/sindresorhus/win-wallpaper/commit/374ceb4f391576aa63d9abc85571af040eeb87bf
    • Linux: Rewrite all the things (#43) 38ea0f4
    Source code(tar.gz)
    Source code(zip)
Owner
Sindre Sorhus
Full-Time Open-Sourcerer. Wants more empathy & kindness in open source. Focuses on Swift & JavaScript. Makes macOS apps, CLI tools, npm packages. Likes unicorns
Sindre Sorhus
A simple CLI tool to create and manage xhelpers-api projects

A simple CLI tool to create and manage xhelpers-api projects

null 2 Feb 25, 2022
⚡️The Fullstack React Framework — built on Next.js

The Fullstack React Framework "Zero-API" Data Layer — Built on Next.js — Inspired by Ruby on Rails Read the Documentation “Zero-API” data layer lets y

⚡️Blitz 12.5k Jan 4, 2023
A desktop live wallpaper app made for Mac.

Wallpieperi A desktop live wallpaper app made for Mac. Status: Alpha Alpha build is going to be released this saturday, however all the code will be a

Jose Moreno Villegas 9 Oct 13, 2022
Wallpaper generator in React.

Reactry's chessboard Reactry's chessboard is wallpaper generator written in React. goals ablity to select a custom color a button to randomize all opt

null 3 Oct 2, 2022
A RESTful API for Bing wallpaper to use easy.

bing-wallpaper A RESTful API for Bing wallpaper to use easy. <img src="https://bingw.jasonzeng.dev/?w=800"/> Usage API Endpoint: https://bingw.jasonze

jasonzeng 31 Dec 15, 2022
Make your wallpaper reminds you of god 🙏

Ayats Wallpapers ?? Next.js Tailwind.css TypeScript Next-themes Swr Prisma PlanetScale Vercel Getting Started Clone the repo and run the following com

Omar Ouhra 11 Oct 15, 2022
Wallpaper Engine but online-version. (HTML, CSS, JS with jQuery, PHP)

Project Preview - Web Wallpaper Engine About Wallpaper Engine but online-version. View animated wallpapers directly in your browser. Case: Create web-

Dmitry Britov 11 Dec 30, 2022
Desktop App for mdSilo: Tiny Knowledge silo on your desktop.

mdSilo A mind silo for storing ideas, thought, knowledge with a powerful writing tool. built with React and Tauri. Demo Discord This is desktop app, a

D.Loh 203 Dec 27, 2022
This provides an extension integration with Docker Desktop to run k9s quickly and easily through the Docker Desktop interface.

k9s extension for Docker Desktop This provides an extension integration with Docker Desktop to allow k9s quickly and easily through the Docker Desktop

James Spurin 14 Dec 16, 2022
Project to manage multiple emails at once with lots of customization. You can send and receive emails. Desktop notifications can be modified.

Technologies Used React Redux Tailwind CSS Features Admin dashboard User settings and or user dashboard send emails recive emails Connections through

Multi Email 9 Dec 17, 2022
This app helps manage a bookstore. It comes in handy when you need to manage a personal book store or library. Entirely built on es6.

Awesome Books A Microverse project on learnong javascript. Additional description about the project and its features. Built With HTML5 CSS3 Javascript

Atugonza ( Billions ) Joel 13 Apr 22, 2022
App to manage maintenance calls. App to manage maintenance calls. This application was created for the purpose of studies.

App to manage maintenance calls. App to manage maintenance calls. This application was created for the purpose of studies.

Rodrigo Gonçalves 112 Dec 26, 2022
One framework. Mobile & desktop.

Angular - One framework. Mobile & desktop. Angular is a development platform for building mobile and desktop web applications using Typescript/JavaScr

Angular 85.6k Dec 31, 2022
Konva.js is an HTML5 Canvas JavaScript framework that extends the 2d context by enabling canvas interactivity for desktop and mobile applications.

Konva Konva is an HTML5 Canvas JavaScript framework that enables high performance animations, transitions, node nesting, layering, filtering, caching,

konva 8.7k Jan 8, 2023
Build performant, native and cross-platform desktop applications with native Vue + powerful CSS like styling.🚀

Vue NodeGui Build performant, native and cross-platform desktop applications with Vue. ?? Vue NodeGUI is powered by Vue ?? and Qt5 ?? which makes it C

NodeGui 765 Dec 30, 2022
Stand-alone parallax scrolling library for mobile (Android + iOS) and desktop. No jQuery. Just plain JavaScript (and some love).

Please note: skrollr hasn't been under active development since about September 2014 (check out the contributions graphs on https://github.com/Prinzho

Alexander Prinzhorn 18.6k Jan 3, 2023
Emulate touch input on your desktop

Touch Emulator Emulate multi-touch input on your desktop. Triggers touch events as specified by W3C. Press the shift key to pinch and rotate! Example

Hammer.js 341 Dec 9, 2022
JavaScript image gallery for mobile and desktop, modular, framework independent

PhotoSwipe Repository JavaScript image gallery for mobile and desktop. Documentation and getting started guide. Demo and script home page. NPM npm ins

Dmitry Semenov 22.5k Dec 30, 2022
One framework. Mobile & desktop.

Angular - One framework. Mobile & desktop. Angular is a development platform for building mobile and desktop web applications using Typescript/JavaScr

Angular 85.7k Jan 4, 2023
:seedling: Next-Gen AI-Assisted Isomorphic Application Engine for Embedded, Console, Mobile, Server and Desktop

lychee.js Mono Repository Important Notes to follow through Installation Quirks: The lycheejs-engine Repository needs to be installed to the path /opt

Cookie Engineer 791 Dec 31, 2022