Does libinput handle touchscreens differently from touchpads?

Yes. Touchscreens operate in absolute coordinate mode and are treated as direct-input devices; touchpads use relative motion with gesture heuristics tuned for indirect pointing. Many libinput options valid for touchpads (tap-to-click, palm detection) are irrelevant or have no effect on touchscreens.

Why does xinput_calibrator not work in a Wayland session?

xinput_calibrator talks to the X server's input system, which is absent in a pure Wayland session. Use the udev LIBINPUT_CALIBRATION_MATRIX property instead; it is read by libinput before the compositor ever sees the device.

How do I rotate touch input to match a rotated display?

On X11, apply a rotation transformation matrix with `xinput set-prop`. Under Wayland, most compositors automatically apply the display's transform to touch input; on Sway you can add a `transform` parameter to the input block if needed.

My touchscreen works in GNOME but not in a bare Sway session — why?

GNOME uses mutter which initialises libinput with sensible defaults and reads udev properties automatically. Sway also uses libinput but requires explicit `input` configuration blocks in ~/.config/sway/config for non-default behaviour such as output mapping or calibration overrides.

Can I use a stylus or active pen with these same settings?

Active pens that present as a separate input device (common on Wacom-protocol hardware) are handled by the libwacom and xf86-input-wacom stack, not standard libinput touchscreen config. Passive styli that just mimic a finger touch work without any additional configuration.

Touchscreen Configuration on Linux

Modern Linux handles most touchscreens automatically through libinput, the unified input handling library used by both Wayland compositors and the X.Org server. Even so, you may need to calibrate the touch surface, map it to the correct display on a multi-monitor setup, enable multi-touch gestures, or work around a device that requires a custom udev rule. This guide walks through the full process from driver verification to gesture configuration.

Verify the Touchscreen Is Detected

Before changing any configuration, confirm the kernel and libinput see the device correctly.

libinput list-devices

Look for an entry whose capabilities include touch. The output will vary but typically reads:

Device:           ELAN Touchscreen
Kernel:           /dev/input/event5
Capabilities:     touch
Tap-to-click:     disabled

If nothing shows up, check whether the kernel module loaded:

dmesg | grep -i touch
lsmod | grep hid

USB touchscreens use usbtouchscreen or HID; I2C panels (common on laptops) typically surface as i2c_hid. If the module is missing, install your distro's kernel extras package and reboot.

Install and Update libinput

Debian / Ubuntu

sudo apt update
sudo apt install libinput-tools xinput xserver-xorg-input-libinput

Fedora / RHEL 9+ / Rocky

sudo dnf install libinput libinput-utils xorg-x11-drv-libinput

Arch Linux

sudo pacman -S libinput xf86-input-libinput

The libinput-tools / libinput-utils package provides the libinput CLI used throughout this guide. Most desktop installs already have these; the commands here ensure everything is present.

Calibration

Touchscreen calibration corrects offset and scaling errors — tapping a point registers a few millimetres away. The approach differs between Wayland and X11.

Check Whether Calibration Is Needed

sudo libinput debug-events --show-keycodes

Touch the screen in each corner and watch the reported coordinates. If they track your finger accurately, the device needs no calibration. Press Ctrl+C to exit.

Calibration on X11 with xinput

The legacy xinput_calibrator tool is still useful under X11 sessions. Install it:

# Debian/Ubuntu
sudo apt install xinput-calibrator

# Arch (AUR)
yay -S xinput-calibrator

xinput_calibrator

Follow the on-screen prompts (tap four targets). The tool prints a configuration snippet. Write it to a persistent file:

sudo tee /etc/X11/xorg.conf.d/99-touchscreen-cal.conf <<'EOF'
Section "InputClass"
    Identifier      "Touchscreen Calibration"
    MatchIsTouchscreen "on"
    Option "CalibrationMatrix" "1.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 1.0"
EndSection
EOF

Replace the matrix values with whatever xinput_calibrator produced. Log out and back in to apply.

Calibration on Wayland via udev

Under Wayland, xinput_calibrator does not work. libinput reads a calibration matrix from the udev property LIBINPUT_CALIBRATION_MATRIX. Find your device's udev node first:

sudo libinput list-devices | grep -A3 -i touch

Note the kernel device path (e.g., /dev/input/event5), then find its udev sysfs entry:

udevadm info --name=/dev/input/event5 | grep -i name

Create a udev rules file with a ATTRS{name} match:

sudo tee /etc/udev/rules.d/99-touchscreen-cal.rules <<'EOF'
ACTION=="add|change", KERNEL=="event[0-9]*", \
  ATTRS{name}=="ELAN Touchscreen", \
  ENV{LIBINPUT_CALIBRATION_MATRIX}="1.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 1.0"
EOF

Replace ELAN Touchscreen with your device name and the matrix with your corrected values. A 3×3 identity matrix means no transform; adjust the translation columns (positions 3 and 7 in row-major order) to shift the touch origin. Reload rules and trigger:

sudo udevadm control --reload-rules
sudo udevadm trigger

A reboot is the safest way to confirm the rule takes effect cleanly.

Mapping a Touchscreen to the Correct Display

On multi-monitor setups the touch input may be mapped across all screens instead of just the panel with the digitizer.

X11 — xinput coordinate transform

Get the touchscreen's xinput ID and the target display name (xrandr output):

xinput list | grep -i touch
xrandr --listmonitors

xinput map-to-output <device-id> HDMI-1

To make it permanent, add this command to your session autostart (~/.xprofile or your desktop environment's autostart facility).

Wayland — compositor-specific settings

GNOME (mutter) handles touch-to-display mapping automatically when only one internal touchscreen is present. For explicit mapping on GNOME:

gsettings set org.gnome.desktop.peripherals.touchscreen:/org/gnome/desktop/peripherals/touchscreens/<usb-id>:usb/ output "['your-connector', '', '']"

The USB ID comes from gsettings list-recursively org.gnome.desktop.peripherals.touchscreen. KDE Plasma 6 exposes touch mapping under System Settings → Input Devices → Touchscreen. For Sway or other wlroots compositors, use input blocks in ~/.config/sway/config:

input "1386:890:ELAN_Touchscreen" map_to_output eDP-1

Multi-Touch Gestures

libinput recognises pinch, swipe, and hold gestures natively. Whether those gestures trigger actions depends on the compositor or gesture daemon in use.

Test Raw Gesture Events

sudo libinput debug-events | grep GESTURE

Perform three- and four-finger swipes on the screen. If you see GESTURE_SWIPE_BEGIN and GESTURE_SWIPE_END events, libinput is reporting them correctly.

Gestures Under GNOME and KDE Wayland

GNOME Shell on Wayland consumes three-finger and four-finger swipes for workspace switching and the Activities overview natively — no extra tooling needed. KDE Plasma 6 similarly handles gestures built-in. If you find gestures unresponsive, confirm you are in a Wayland session:

echo $XDG_SESSION_TYPE

Gestures on X11 or Lightweight Wayland Compositors

Use libinput-gestures to map gesture events to key bindings or shell commands.

# Debian/Ubuntu
sudo apt install libinput-gestures

# Arch
sudo pacman -S libinput-gestures

# Fedora (from COPR or build from source)
sudo dnf install python3-evdev python3-pyudev
git clone https://github.com/bulletmark/libinput-gestures.git
cd libinput-gestures && sudo make install

Add your user to the input group so it can read raw device events without root:

sudo usermod -aG input $USER

Log out and back in, then configure gestures in ~/.config/libinput-gestures.conf:

gesture swipe left  3  xdotool key super+Page_Down
gesture swipe right 3  xdotool key super+Page_Up
gesture pinch in    2  xdotool key ctrl+minus
gesture pinch out   2  xdotool key ctrl+plus

Enable and start it as a user service:

libinput-gestures-setup autostart start

Verify Everything Works

sudo libinput list-devices
libinput measure touch-size --device /dev/input/event5

The second command reports the physical touch contact size, confirming the driver is returning full multi-touch data. On X11 you can also run:

xinput list-props <device-id> | grep -i calib

to confirm calibration properties were applied.

Troubleshooting

Touch events detected but cursor does not move: The device may be in "direct" mode (absolute coordinates) but mapped to a zero-sized area. Under X11, confirm xinput list-props shows a valid coordinate transformation matrix. Under Sway, check swaymsg -t get_inputs.
Wayland gestures not working after libinput-gestures install: Your compositor may be consuming the gestures first (especially GNOME). Try removing GNOME's built-in gesture bindings or switching to a different gesture count.
udev calibration rule ignored: Verify the ATTRS{name} matches exactly — it is case-sensitive. Run udevadm test /sys/class/input/event5 and inspect the output for your property.
Touch offset drifts after screen rotation: Screen rotation changes the coordinate transform. Under X11, re-run xinput set-prop with a rotation matrix after each xrandr rotation. Under Wayland compositors, touch mapping usually follows display rotation automatically, but some wlroots-based compositors require an explicit transform in the input block.
I2C touchscreen not seen at all after suspend: This is a known firmware issue on some hardware. Add a udev rule or systemd sleep hook to reload the i2c_hid module on resume: modprobe -r i2c_hid && modprobe i2c_hid.