Skip to content

kscreen-doctor

kscreen-doctor can be used to enable and disable outputs, position screens, and change resolution (mode setting).

Show runtime information: backends, logging and more

kscreen-doctor -i

Show configuration in JSON format

kscreen-doctor -j

Show outputs from monitors

kscreen-doctor -o

Write a comment to the KScreen log (requires logging enabled)

KSCREEN_LOGGING=1 kscreen-doctor -l "Manual display change via script"

Log and enable a specific output (HDMI-1)

KSCREEN_LOGGING=1 kscreen-doctor -l "Enable HDMI-1" -o HDMI-1.enable

Log a layout-related operation while listing outputs

KSCREEN_LOGGING=1 kscreen-doctor --log "Reset display layout" --outputs

Log and disable DPMS for all displays (Wayland)

KSCREEN_LOGGING=1 kscreen-doctor -l "DPMS off for all displays" -d off

Logging attempt without KSCREEN_LOGGING enabled (expected error)

$ kscreen-doctor -l "Manual display change via script"
kscreen-doctor: Logging is disabled, unset KSCREEN_LOGGING in your environment.

Fix the 'Logging is disabled' error

export KSCREEN_LOGGING=1

Then run:

kscreen-doctor -l "Manual display change via script"
kscreen-doctor -o HDMI-1.enable

Enable logging for a single command (cleanest)

KSCREEN_LOGGING=1 kscreen-doctor -l "Enable HDMI-1" -o HDMI-1.enable

Recommended real-world usage (best practice)

This stores kscreen.log in your home directory.

LOG="$HOME/kscreen.log"

echo "### Enable HDMI-1 $(date)" >> "$LOG"
KSCREEN_LOGGING=1 kscreen-doctor -l "Enable HDMI-1" -o HDMI-1.enable >> "$LOG" 2>&1

Disable HDMI output, enable laptop panel, and set a specific mode

kscreen-doctor output.HDMI-2.disable output.eDP-1.mode.1 output.eDP-1.enable

Position the HDMI monitor to the right of the laptop panel

kscreen-doctor output.HDMI-2.position.1280,0 output.eDP-1.position.0,0

Set resolution mode

kscreen-doctor output.HDMI-2.mode.1920x1080@60

Set scale (fractional scaling supported on Wayland only)

kscreen-doctor output.HDMI-2.scale.2

Set rotation

Possible values: none, left, right, inverted, flipped, flipped90, flipped180, flipped270

kscreen-doctor output.HDMI-2.rotation.left

Set HDR mode

Possible values: enable, disable

kscreen-doctor output.HDMI-2.hdr.enable

Set SDR brightness (HDR screens only)

Possible values: 100–1000

kscreen-doctor output.HDMI-2.sdr-brightness.300

Set brightness on non-HDR screens

Possible values: 0–100

kscreen-doctor output.HDMI-2.brightness.10

Enable wide color gamut (WCG)

kscreen-doctor output.HDMI-2.wcg.enable

Set ICC profile path

kscreen-doctor output.HDMI-2.iccprofile.\"/path/to/profile.icc\"

Show DPMS information

kscreen-doctor --dpms show

Set DPMS mode

Possible values: on, off

kscreen-doctor --dpms on