xbacklight
Adjust display backlight brightness
TLDR
Get the current screen brightness as a percentage
Set the screen brightness to 40%
Increase current brightness by 25%
Decrease current brightness by 75%
Increase backlight to 100%, over 60 seconds (value given in ms), using 60 steps
SYNOPSIS
xbacklight [-get | -set <percentage> | -inc <percentage> | -dec <percentage>] [-time <milliseconds>] [-steps <number>] [-fps <frames_per_second>]
PARAMETERS
-get
Get the current backlight brightness level as a percentage (0 to 100).
-set <percentage>
Set the backlight brightness to the specified percentage (0 to 100).
-inc <percentage>
Increase the backlight brightness by the specified percentage. Can be combined with -time for a fade effect.
-dec <percentage>
Decrease the backlight brightness by the specified percentage. Can be combined with -time for a fade effect.
-time <milliseconds>
Specify the duration (in milliseconds) over which a brightness change should occur, enabling a smooth fade effect. Used with -inc or -dec.
-steps <number>
Define the number of discrete steps to use when fading the brightness. More steps generally result in a smoother fade. Used with -time.
-fps <frames_per_second>
Set the frames per second for the fade animation. This determines how quickly the brightness changes are rendered during a fade. Used with -time.
DESCRIPTION
xbacklight is a command-line utility for controlling the backlight brightness of displays connected to an X.Org server. It leverages the RandR (X Resize, Rotate and Reflect) extension to interact with the display hardware. Unlike some other backlight control tools, xbacklight operates within the X session environment, making it particularly useful for desktop users running X.Org.
It provides functionalities to query the current brightness, set it to a specific percentage, or incrementally increase/decrease it. Furthermore, it supports smooth transitions (fades) over a specified duration, providing a more pleasant user experience than abrupt changes. While effective for X.Org, its functionality is limited to this display server and typically does not work with newer display protocols like Wayland.
CAVEATS
xbacklight relies exclusively on the X.Org RandR extension. It will not work on systems using other display servers like Wayland.
Some graphics drivers may not fully support RandR backlight control, or might require specific kernel modules or specific X.Org configuration.
In certain scenarios, adjusting brightness might require root privileges or proper user group permissions (e.g., being in the 'video' group).
PERMISSIONS
Ensure your user has the necessary permissions to control display settings, often by being part of the 'video' group or by using 'sudo' if system-wide changes are needed. Incorrect permissions are a common reason for xbacklight failing.
DRIVER SUPPORT
Functionality is heavily dependent on your graphics driver's support for the RandR backlight property. If xbacklight doesn't work as expected, investigate your graphics driver configuration and ensure it properly exposes backlight control via RandR.
HISTORY
xbacklight is a part of the X.Org utility suite, developed to provide a standard command-line interface for backlight control through the X RandR extension. Its development is intertwined with the evolution of the RandR extension itself, which became a widely adopted mechanism for display management within the X Window System. It emerged as a convenient tool for users and scripts to adjust display brightness without relying on hardware hotkeys or specific desktop environment controls, particularly prevalent in lightweight desktop environments or tiling window managers.
SEE ALSO
brightnessctl(1), light(1), xrandr(1)