xgamma GUI Tool

Graphical tool for managing display gamma settings using the xgamma command on Linux systems.

Why you might need this tool?

If your old and cheap monitor is displaying incorrect colors, you might need to adjust its gamma settings to fix them. This tool is for those who want to avoid making those adjustments through the terminal.

Description

xgamma GUI Tool provides a simple, minimalist interface for adjusting gamma correction for red, green, and blue channels individually or together. It allows you to preview changes in real-time and automatically apply saved settings on system startup.

Download

Canonical repository (source and releases): github.com/pgorithm/xgamma-gui-tool

Pre-built .deb packages are published on the Releases page for that repository only. Do not treat other spellings or forks as the official distribution channel unless you explicitly trust them.

Verify the .deb package (integrity)

Published releases attach a SHA256SUMS file alongside the .deb. Download both into the same directory, then run:

sha256sum -c SHA256SUMS

You should see OK for the .deb filename. If the check fails, do not install; re-download from the release page.

Requirements

• Linux Mint / Ubuntu (tested on Linux Mint 22.2)
• Python 3.8 or higher
• xgamma (x11-xserver-utils package)
• PyQt5

PATH and trusted executables (SEC-001)

The app locates xgamma, xrandr, and systemd-detect-virt by name on your PATH, like a shell would: the first matching executable wins. If an attacker or a misconfigured account prepends a writable directory to PATH, a malicious binary with those names could run instead of the system tools.

Recommendations: install packages from your distribution (e.g. x11-xserver-utils on Debian/Ubuntu) so tools normally live under /usr/bin; avoid prepending untrusted or world-writable directories to PATH when starting the app; on shared or high-risk systems, use a minimal PATH for your session.

Optional hardening: set XGAMMA_GUI_TOOL_TRUSTED_PREFIXES to a list of allowed directory roots, separated with the same character as PATH (: on Linux). Only executables whose resolved path lies under one of these directories are used. Example:

export XGAMMA_GUI_TOOL_TRUSTED_PREFIXES="/usr/bin:/bin"
python3 main.py

If no executable matches those prefixes, the app behaves as if the tool were missing (e.g. no xgamma → startup dependency warning). When the variable is unset, behavior is unchanged from earlier releases (first match on PATH).

Quick setup (fresh system)

Run the following commands one by one in the terminal:

sudo apt update && sudo apt upgrade -y
sudo apt install -y python3 python3-venv python3-pip git x11-xserver-utils
wget https://github.com/pgorithm/xgamma-gui-tool/archive/refs/heads/main.zip -O xgamma-gui-tool-main.zip
unzip xgamma-gui-tool-main.zip
cd xgamma-gui-tool-main
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
python3 main.py

Installation

1. Install xgamma

Ubuntu/Debian:

sudo apt-get install x11-xserver-utils

Fedora:

sudo dnf install xorg-x11-server-utils

Arch Linux:

sudo pacman -S xorg-xgamma

2. Install Python dependencies

pip install -r requirements.txt

Or using pip3:

pip3 install -r requirements.txt

Translations (i18n)

The app uses Qt QTranslator. With a Russian system locale or LANG=ru_RU.UTF-8, main window strings, dialogs, and environment warnings are shown in Russian (embedded catalog, or src/translations/xgamma_gui_ru.qm if you add one).

To maintain .ts / .qm files, see src/translations/README.txt.

Usage

Running the application

From the project root directory:

python main.py

Or:

python3 main.py

Features

• Individual channel control: Adjust red, green, and blue gamma values separately
• Overall gamma control: Adjust all channels simultaneously
• Real-time preview: See changes immediately on the reference test pattern
• Keyboard adjustments: Click any slider once and fine-tune it with the ←/→ arrow keys (hold Shift for larger steps)
• Autostart support: Save settings to be applied automatically on system startup
• Reset function: Quickly reset all values to default (1.0) and remove autostart entries

Interface

• Reference image: Test pattern with gradients and color blocks for visual calibration
• Sliders: Horizontal sliders for each color channel (Red, Green, Blue) and overall gamma (All)
• Value inputs: Numeric fields showing current slider values (editable)
• Keyboard control: Click a slider or value field to focus it, then use the keyboard arrows (Shift+arrow for 10× steps) to adjust without using the mouse
• Reset button: Resets all values to 1.0 and removes autostart entries
• Save to Autostart button: Saves current settings to be applied on system startup

Gamma Range

• Minimum: 0.010
• Maximum: 5.000
• Step: 0.001
• Default: 1.000 for all channels

Project Structure

xgamma-gui-tool/
├── main.py                 # Entry point (can be run from root)
├── src/
│   ├── __init__.py
│   ├── main.py            # Main application entry point
│   ├── gamma_core.py      # Gamma management logic
│   ├── command_resolution.py  # PATH / trusted-prefix lookup for external commands
│   ├── gui.py             # GUI implementation
│   ├── config_manager.py  # Autostart configuration
│   └── reference_image.py # Reference image generation
├── requirements.txt       # Python dependencies
├── gamma_adjust.desktop   # Desktop file template
└── assets/
    └── icons/             # Application icons

Autostart

Moving the sliders applies gamma to the display immediately (with a short debounce). The Save to autostart button (tooltip explains this) creates or overwrites ~/.config/autostart/xgamma_gui_tool.desktop so the same xgamma command runs on the next login. Reset sets gamma to 1.0 and removes only that application autostart file, not other .desktop entries that mention xgamma.

Error Handling

• If xgamma is not installed, the application will display a warning message with installation instructions and exit
• Invalid numeric inputs are automatically corrected
• Status messages appear in the status bar at the bottom of the window
• Warnings appear if gamma manipulation might be limited

Checking Gamma Control Support

Some environments prevent xgamma from changing the picture. Use these checks before assuming the app is broken:

• In-app warning indicator: A yellow warning icon appears whenever the tool detects a virtual machine or HDR/10-bit output pipeline; hover it to read the exact reason.
• Virtual machines: Run systemd-detect-virt (expect none on bare metal) or inspect /sys/class/dmi/id/product_name. If virtualization is detected, enable GPU pass-through/3D acceleration or switch to a native Linux session because many VM display drivers ignore gamma commands.
• HDR or 10-bit modes: Run xrandr --verbose | grep -i "hdr\|10 bpc\|10-bit" to see whether an HDR pipeline is active. Disable the HDR toggle in your desktop environment or force 8-bit color before retrying, because X11 gamma ramps are bypassed when HDR is enabled.

Development note

This project was built with help from Cursor, an AI-assisted code editor. If you are uncomfortable using software that was created with AI, you are welcome to skip this tool entirely—we promise not to tell anyone.

License

This project is provided as-is for educational and mentoring purposes.

Documentation

For xgamma command documentation, see: https://yuweijun.github.io/manpages/man1/xgamma.1.html