Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time



Brightness indicator/control widget for awesome wm based on xbacklight or brightnessctl.


The module requires either xbacklight or brightnessctl to work. Thus, on archlinux, you'll need to install at least one of the following system packages:

I've experienced xorg-xbacklight not work on certain laptops. So, if you find that the widget is not working, try a different backend.


Drop the script into your awesome config folder. Suggestion:

cd ~/.config/awesome
git clone


In your ~/.config/awesome/rc.lua:

-- Import and instanciate:
local brightness_ctrl = require("brightness") {
    -- pass options here

-- Add widget to the wibox:
s.mywibox:setup {
    { -- Right widgets

Note that you need to pass .widget to the wibox, not the instance itself!

The flag brightness_ctrl.is_valid indicates successful initialization.

Usage options

Full example:

local brightness_ctrl = require("brightness") {
  backend = nil,
  step = 5,
  timeout = 3,
  levels = {1, 25, 50, 75, 100},

backend Picks command with which to perform brightness queries and updates. Allowed values are nil (meaning autodetect), "xbacklight" or "brightnessctl". Default: nil.

step How many percentage points to increase or decrease the brightness level when clicking the widget. Default: 3.

timeout Interval in seconds at which to check the current brightness level and update the widget text. Default: 5.

levels Cycle through these brightness percentages on middle-click. Default: ``{1, 25, 50, 75, 100}`.


If you get errors on startup, try executing xbacklight -get or brightnessctl -c backlight get in a terminal.

If you get the error "No outputs have backlight property", make sure you have installed an appropriate display driver, e.g. for intel cards:

sudo pacman -S xf86-video-intel

You may need to restart afterwards.