Adjust X Display Gamma Safely with xgamma

xgamma queries an X display's gamma, lets you set one value or separate red, green and blue levels, then verify the change. It changes only the value held by the X server for the selected display, not a system configuration file, and does not require elevated privileges when your X session allows the connection.

This guide covers xgamma 1.0.7 from Debian package x11-xserver-utils version 7.7+10build2, using the installed manual page as the behaviour reference. Allow about ten minutes. You need a running X server and permission to connect to it. A Wayland-only session is not enough for this command.

Safety boundary: Gamma changes affect the display output for the X server and can make the screen difficult to read. Record the values before changing them. The examples below do not use sudo, and adding it will not fix a missing or inaccessible X display.

1. Confirm the installed command

Check which binary will run and confirm its version. These are ordinary read-only commands:

$ command -v xgamma
/usr/bin/xgamma
$ xgamma -version
xgamma 1.0.7

The package version and utility version are separate pieces of information. If your version differs, check its local manual page with man xgamma before relying on option details.

2. Select the X display

xgamma uses the DISPLAY environment variable by default. Inspect it before running a query:

$ printf 'DISPLAY=%s\n' "${DISPLAY:-<unset>}"
DISPLAY=:0

Your value may be different. If you need to target another server, pass -display explicitly, for example:

$ xgamma -display host.example:0

Do not guess a display name. A connection failure is safer than changing the wrong session. The server must also permit your user to connect. If the variable is unset, the command normally fails with an error such as unable to open display '' and a non-zero status.

3. Query and record the current values

Run xgamma without a gamma option. With no value supplied, it prints the current gamma correction:

$ xgamma
Red 1.000, Green 1.000, Blue 1.000

The exact formatting and values are display-specific, so treat the output above as an example rather than a default to copy. Save the three reported values somewhere you can reach if you need to undo the next step. Confirm that the query itself succeeded:

$ xgamma >/tmp/xgamma-current.txt
$ status=$?
$ printf 'xgamma status: %s\n' "$status"
xgamma status: 0

The temporary file contains the normal output from the query. This is a read-only check, and the file can be removed after you have recorded the values. Do not use the output from a failed command as a baseline.

4. Apply one gamma value

Use -gamma when red, green and blue should receive the same value. The argument is a floating-point value accepted by the X server. Start with a small, deliberate test and keep the original values:

$ xgamma -gamma 1.10
$ printf 'xgamma status: %s\n' "$?"
xgamma status: 0

There is no universal visual result to predict: the monitor, driver and existing colour pipeline all matter. A successful exit means the request was accepted by the client and server path. The installed manual page warns that whether the video driver honours the values is driver-dependent.

Recovery: Query the display again, then reapply the values you recorded in step 3. For example, if the original values were 1.00, 1.00 and 1.00:

$ xgamma -rgamma 1.00 -ggamma 1.00 -bgamma 1.00
$ xgamma
Red 1.000, Green 1.000, Blue 1.000

Use your recorded values, not these example numbers, when restoring a display that had a different calibration.

5. Apply separate RGB values

Use -rgamma, -ggamma and -bgamma when the channels need different corrections. You can provide one, two or all three of these options according to the command syntax, but an explicit complete set is easier to audit:

$ xgamma -rgamma 1.05 -ggamma 1.00 -bgamma 0.95
$ printf 'xgamma status: %s\n' "$?"
xgamma status: 0
$ xgamma
Red 1.050, Green 1.000, Blue 0.950

The server receives gamma values with three decimal places of accuracy. Do not imply more precision in a calibration record than the command can transmit. If the output does not change as expected, check the driver support before repeatedly adjusting values.

6. Target a screen in a multi-screen display

When the X server exposes multiple screens as one logical display, select the intended screen with -screen. This example targets screen 1 on the display named by DISPLAY:

$ xgamma -screen 1 -gamma 1.05
$ printf 'xgamma status: %s\n' "$?"
xgamma status: 0

Only use a screen number you have verified in your X configuration or display tooling. If you are unsure whether your setup has this older multi-screen arrangement, omit -screen and query the default display first.

7. Diagnose the common failures

A missing display connection is the most common trap:

$ xgamma
xgamma:  unable to open display ''
$ printf 'xgamma status: %s\n' "$?"
xgamma status: 1

Check DISPLAY, confirm that an X server is running, and run the command from the user session that owns the display. If you use an explicit remote display, check the host and display number and the server's access policy. Do not work around an access error by weakening X authentication.

Use -quiet when a script needs no normal output, but still check the exit status:

$ if xgamma -quiet -gamma 1.00; then
>     printf '%s\n' 'gamma request accepted'
> else
>     printf '%s\n' 'gamma request failed' >&2
> fi
gamma request accepted

Do not parse normal human-readable output as a scripting interface. For a script, use the status for success and keep the display target explicit.

Done means