Chwall {ʃwal} is tiny automatic wallpaper changer, written in python.

It's name is the contraction of change wallpaper, which may be pronounced as a twisted version of cheval, which means horse in french.

Goal and features

Easily change your wallpaper from time to time, benefiting from various online sources and your own wallpapers collections.

Chwall is currently able to retrieve pictures from the following sources:

  • your local folders
  • bing pictures of the day
  • National Geographic pictures of the day
  • NASA astronomical pictures of the day
  • deviantart RSS feeds
  • Unsplash random API (requires a free account to access their API)


pip install -r requirements.txt
python setup.py install

You can also install it system-wide with the provided Makefile


Put the chwall.yml.example file in ~/.config/ and tune it as you want. This file is not mandatary.

The chwall.yml config file is a YAML file with several top level objects:

  • general will contains preferences, which are used by chwall to operate as intended.
  • one key for each activated (or not) picture sources.

general may contains the following subkeys:

  • lightdm_wall the path to a writable file, which will always contains the last set wallpaper. This is usefull to display the same wallpaper on lightdm than on your desktop, without having to open too widely your home folder. Use something in /var/cache for exemple.
  • sources is an array containing the activated pictures sources. By default, only bing and natgeo are activated. The sources must be one or more of: bing, natgeo (for the National Geographic picture of the day), nasa (for the NASA astronomical picture of the day), unsplash, deviantart, or local (for your local folders).
  lightdm_wall: /var/cache/last-wall
    - bing
    - natgeo
    - nasa
    - deviantart
    - unsplash
    - local

Add local folders to inspect

In order to display wallpaper from your own local collection, just add the top level key local to the chwall.yml file. This variable must contains an option named paths, which must contain an array listing folder path. you can use * or ** as placeholder. See python glob documentation to know more how to write your folder paths.

    - ~/Pictures/mywall/*
    - /usr/share/wallpapers/**

Set the Bing region to fetch picture from

Add the top level key bing to your chwall.yml file, containing an option named locales, which must list locale names. See the appropriate Bing page to know more about the available regions. If you add more than one locale (at least one is required!), duplicate pictures won't be add to the pending list.

    - fr-FR
    - en-US
    - de-DE
    - ja-JP

Set the picture resolution for National Geographic

Add the top level key natgeo to your chwall.yml file. Then, add a subkey named width under it, with one of the following value: 240, 320, 500, 640, 800, 1024, 1600, or 2048. The default value is 1600.

  width: 2048

Set the picture resolution for Unsplash

Add the top level key unsplash to your chwall.yml file. Then, add a subkey named width under it, with the value of your choice. This value should be the width of your screen. The default value is 1600.

  width: 1920

Retrieve pictures from an Unsplash collection

To do so, you must register an application on Unsplash in order to consume their API. Once this is done, you must add the subkey access_key under the unsplash key in your chwall.yml config file.

Then, you have access to the collections subkey, which let you specify one or more public collections IDs. If you don't give any, pictures will be retrieved randomly from all the Unsplash website.

  width: 1920
  access_key: [your access key]
    - 1510726

The count subkey let you choose how many pictures you want to retrieve from Unsplash. You are limited to 30 by the API, and the default is 20.

  width: 1920
  access_key: [your access key]
  count: 10

Add Deviantart RSS Feeds

Deviantart RSS feeds follow the same URL pattern: https://backend.deviantart.com/rss.xml?q=[REQUEST]&type=deviation

All you have to do is to add the top level key deviantart to your chwall.yml file, containing an option named collections, which must list [REQUEST] items.

    - in%3Acustomization%2Fwallpaper+1440x900
    - gallery%3Amattahan%2F59801



Chwall is being translated using Weblate, a web tool designed to ease translating for both developers and translators.

You can also fetch the gettext files directly from the source code tree and send your changes as a pull request (see bellow).


The canonical repository is located at https://git.deparis.io/chwall. Mirror exists on Framagit and on Github.

Merge request and issues are accepted on all mirrors or by mail to the main author.


The icon is resized from the work of Bernd Wachtmeister (Touchstone).