Skip to content
Python wallpaper setter for X11
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Python wallpaper-setter for X11.

This was originally written as an extension for the Qtile window manager (hence the name qpaper), though it works for X11 in general. It requires the same dependencies as Qtile, i.e. cairocffi and xcffib.


The qpaper.Painter acts as the wallpaper setting interface. Instantiate it with the name of the target display, and then either all screens can be painter by using the Painter.paint_all method, or an individual screen using the Painter.paint_screen method. These two methods can both take optional these keyword args:

  • image (str) : path to image to set as wallpaper
  • colour (str) : hex code to simply set a colour instead of an image
  • option (str) : one of 'fill' or 'stretch'

Painter.paint_screen should also be passed an int to index the target screen.


Installation via also installs a script named qpaper that can be used directly:

qpaper /path/to/wallpaper/image.png --option fill


To set wallpapers for all screens upon Qtile startup, add something like this to the Qtile config:

import os
import qpaper
from libqtile import hook

def startup():
        image='/home/user/wallpaper.png', option='fill',
You can’t perform that action at this time.