This is a pre-production deployment of Warehouse. Changes made here affect the production instance of PyPI (
Help us improve Python packaging - Donate today!

Automatically adjust Linux display brightness

Project Description

The auto-adjust-display-brightness program automatically adjusts the brightness of Linux computer displays based on whether it’s light or dark outside. To get it working you create a configuration file defining your physical location (this is how it figures out whether it’s light or dark outside) and how to manage the brightness of which displays (so it knows the best way to control the brightness).

I’m a computer programmer and sometimes work through the evening and into the night because it enables deep concentration. During such evenings / nights a recurring irritation was that I had to manually adjust the brightness of my laptop screen and the external monitor attached to my laptop to avoid unnecessary eye strain. I’d been using xflux for years (it removes the blue light from computer displays during the evening) but that doesn’t dim the backlight of my MacBook Air while I found this to be essential to avoid eye strain.


The auto-adjust-display-brightness program is written in Python and is available on PyPI which means installation should be as simple as:

$ pip install auto-adjust-display-brightness

There’s actually a multitude of ways to install Python packages (e.g. the per user site-packages directory, virtual environments or just installing system wide) and I have no intention of getting into that discussion here, so if this intimidates you then read up on your options before returning to these instructions ;-).

Getting started

The auto-adjust-display-brightness program requires a configuration file that defines your physical location (this is how it figures out whether it’s light or dark outside) and how to manage the brightness of which displays (so it knows the best way to control the brightness). As an example here’s the configuration file that I’m using at the moment:

# My physical location. I determined these values using Google Maps.
latitude = 53.240534499999995
longitude = 6.614897599999949
elevation = -2

# The laptop screen of my MacBook Air. This controls the physical backlight
# which is the best way to reduce the brightness (it also reduces power
# consumption :-).
[display:MacBook Air]
min-brightness = 7
max-brightness = 70
sys-directory = /sys/class/backlight/acpi_video0

# My external monitor connected via a display port to DVI adapter. I haven't
# found any way to configure the physical backlight of this monitor so I'm
# resorting to a software only modification here (better than nothing).
[display:ASUS monitor]
min-brightness = 30
max-brightness = 60
output-name = HDMI1

The configuration file is loaded from the following locations:

  • ~/.auto-adjust-display-brightness.ini
  • /etc/auto-adjust-display-brightness.ini

The structure of the configuration file is as follows:

  • The [location] section has three items, all of which are required (latitude, longitude and elevation). Some hints on how to find the correct values:
    • You can find your latitude and longitude on Google Maps.
    • Finding your elevation is a bit trickier: Google Maps has the required information but doesn’t expose it. Fortunately there are a dozen online tools that make it easy to find your elevation.
  • Each [display:...] section defines a computer display whose brightness should be controlled by the program:
    • The label after the display: tag is the name of the display (it’s used in logging output but not otherwise significant, although it should of course be unique).
    • Displays may have a configured minimum brightness (min-brightness) and maximum brightness (max-brightness). These items default to 0% and 100% respectively (the values are percentages).
    • Currently two types of brightness control are supported:
      1. The physical brightness of the backlight of laptop screens. This uses the Linux sysfs virtual file system’s /sys/class/backlight interface to control backlight brightness. The only required item is sys-directory which is expected to contain the absolute pathname of the directory that controls the backlight brightness of your laptop screen (you’ll have to figure this out for yourself).
      2. The software brightness of any display using xrandr to apply a software only modification of display brightness. The main advantage of this approach is that it will (should) always work. The disadvantage is that it won’t dim the back light of the screen. In other words, if you can get the other type of brightness control to work for your display it’s likely preferable.

Running from cron

To actually have your display brightness adjusted without manually running any commands you can run auto-adjust-display-brightness from a cron schedule. Here’s what I’m currently using:

# /etc/cron.d/auto-adjust-display-brightness:
# Crontab entries for automatic adjustment of display brightness.


@reboot root $VIRTUAL_ENV/bin/auto-adjust-display-brightness --force 1>/dev/null 2>&1
* * * * * root $VIRTUAL_ENV/bin/auto-adjust-display-brightness 1>/dev/null 2>&1

Some notes about this crontab:

  • The @reboot line is responsible for running the program straight after boot to avoid the display brightness starting in the wrong state and being decreased or increased gradually in the minutes after I’ve booted my laptop. When the program detects that it’s being run less than 60 seconds after the system has booted it changes the brightness at once instead of gradually.
  • The commands are run as root so that the program has the privileges required to write to /sys/class/backlight/acpi_video0 (to control the physical backlight of my MacBook Air).
  • The DISPLAY variable enables xrandr to work even though it’s not being run from within my GUI environment.
  • The HOME variable enables auto-adjust-display-brightness to find my configuration file without having to move it to /etc/auto-adjust-display-brightness.ini. This enables me to track the configuration file in my private dotfiles git repository :-).


The latest version of auto-adjust-display-brightness is available on PyPI and GitHub. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at


This software is licensed under the MIT license.

© 2016 Peter Odding.

Release History

Release History

This version
History Node


History Node


History Node


History Node


History Node


History Node


Download Files

Download Files

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

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
auto-adjust-display-brightness-1.3.1.tar.gz (15.3 kB) Copy SHA256 Checksum SHA256 Source Apr 17, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting