Skip to main content

A Python module for controlling power and brightness of the official Raspberry Pi 7" touch display.

Project description


A Python module for controlling power and brightness of the official Raspberry Pi 7" touch display.

PyPI Python Version Downloads Documentation License Black Build Read the Docs Issues


Note: This GIF was created using the old v1 API, so please don't use it as API reference 🙂


  • Set the display brightness smoothly or abrupt
  • Set the display power on or off
  • Get the current brightness
  • Get the display power state (on/off)
  • Command line interface
  • Graphical user interface


  • A Raspberry Pi or ASUS Tinker Board including a correctly assembled 7" touch display v1.1 or higher (look on the display's circuit board to see its version), or a Surface RT running a Linux-based OS
  • Python 3.6+
  • Optional: Raspberry Pi: pygobject for the GUI, already installed on a recent Raspbian
  • Optional: Tinker Board: gir1.2-gtk-3.0 for the GUI install


Install from PyPI:

$ pip3 install rpi-backlight

Note: Create this udev rule to update permissions, otherwise you'll have to run Python code, the GUI and CLI as root when changing the power or brightness:

$ echo 'SUBSYSTEM=="backlight",RUN+="/bin/chmod 666 /sys/class/backlight/%k/brightness /sys/class/backlight/%k/bl_power"' | sudo tee -a /etc/udev/rules.d/backlight-permissions.rules


For testing without a physical display (e.g. on your main Linux/macOS/Windows machine) you can use linusg/rpi-backlight-emulator.



Example in a Python shell:

>>> from rpi_backlight import Backlight
>>> backlight = Backlight()
>>> backlight.brightness
>>> backlight.brightness = 50
>>> backlight.brightness
>>> with backlight.fade(duration=1):
...     backlight.brightness = 0
>>> backlight.fade_duration = 0.5
>>> # subsequent `backlight.brightness = x` will fade 500ms
>>> backlight.power
>>> backlight.power = False
>>> backlight.power

For more details see docs.


Open a terminal and run rpi-backlight.

$ rpi-backlight -b 100
$ rpi-backlight --set-brightness 20 --duration 1.5
$ rpi-backlight --get-brightness
$ rpi-backlight --get-power
$ rpi-backlight -p off
$ rpi-backlight --get-power
$ rpi-backlight --set-power off :emulator:
$ rpi-backlight -p toggle
$ rpi-backlight -p toggle -d 1.5

For all available options see docs.


Open a terminal and run rpi-backlight-gui.

Graphical User Interface Graphical User Interface (2)

Adding a shortcut to the LXDE panel

Panel result

See docs.


Tests use pytest, install with pip3 install pytest.

Now, run from the repository root directory:

$ python3 -m pytest


Please free to open an issue for bug reports and to discuss new features - pull requests for new features or bug fixes are welcome as well!


The source code and all other files in this repository are licensed under the MIT license, so you can easily use it in your own projects. See LICENSE for more information.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

rpi-backlight-2.6.0.tar.gz (10.5 kB view hashes)

Uploaded source

Built Distribution

rpi_backlight-2.6.0-py3-none-any.whl (10.1 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page