How to Debug Input Devices and Touchpad Gestures in Linux Using libinput

Modern Linux desktop environments running Wayland or Xorg (including GNOME, KDE Plasma, Sway, and Hyprland) handle mouse, keyboard, touchpad, and touchscreen input through the libinput library. Designed to provide consistent multi-touch gestures, palm detection, and pointer acceleration curves across hardware vendors, libinput serves as the primary abstraction layer between the Linux kernel input subsystem (evdev) and desktop compositors.

When input devices behave erratically—such as when a touchpad fails to register two-finger scrolling, multi-finger gestures drop intermittently, or palm detection triggers false positives while typing—legacy X11 utilities like xinput cannot diagnose issues under Wayland. The libinput-tools package provides low-level command-line diagnostics to monitor raw event streams, measure hardware pressure, and audit gesture recognition directly.

Installing libinput Diagnostic Utilities

The diagnostic commands are packaged separately from the base library across major distributions. Install the tools package using your package manager:

# Ubuntu / Debian
sudo apt install -y libinput-tools

# Fedora / RHEL / Rocky Linux
sudo dnf install -y libinput-utils

# Arch Linux
sudo pacman -S libinput

Listing and Auditing Input Hardware Devices

To inspect all recognized input hardware connected to your machine, execute:

sudo libinput list-devices

The output groups hardware into structured blocks corresponding to kernel event nodes (e.g., /dev/input/event4):

• Device: The friendly hardware name reported by ACPI or USB descriptors.
• Kernel: The corresponding /dev/input/event* device node.
• Capabilities: Declared hardware roles (e.g., keyboard, pointer, touch, gesture).
• Tap-to-click: Indicates whether tapping is supported and currently enabled.
• Accel profiles: Supported pointer acceleration profiles (typically flat or adaptive).

Monitoring Real-Time Event Streams with debug-events

To view raw input events as they occur in real time, run the debug-events command:

sudo libinput debug-events

To isolate output to a single input device (such as your touchpad at /dev/input/event4), pass the --device flag:

sudo libinput debug-events --device /dev/input/event4

As you interact with the device, the terminal prints live event records:

event4   POINTER_MOTION    +0.012s    2.45/  -1.80 ( +3.00/  -2.00)
event4   GESTURE_SWIPE_BEGIN +1.240s  3
event4   GESTURE_SWIPE_UPDATE +1.252s 3   0.12/ -14.20
event4   GESTURE_SWIPE_END   +1.410s  3
event4   TOUCH_DOWN        +2.100s  0 (0)  34.20/ 78.40
event4   TOUCH_UP          +2.250s  0 (0)

Interpreting Event Types:

• POINTER_MOTION: Standard pointer delta coordinates.
• GESTURE_SWIPE_*: Multi-finger swipe events, indicating finger count and directional velocity.
• GESTURE_PINCH_*: Multi-finger pinch-to-zoom gestures with scaling factors and angle deltas.
• TOUCH_DOWN / TOUCH_UP: Raw finger contact and release coordinates.

Measuring Touchpad Pressure and Palm Detection

If your touchpad registers clicks unintentionally while resting your palms on the keyboard deck, use the measure utility to determine whether the hardware reports finger contact pressure:

sudo libinput measure touchpad-pressure /dev/input/event4

The utility prompts you to touch the pad with normal finger taps, hard presses, and palm rests, displaying real-time pressure values. If the pressure readings remain constant regardless of force, the touchpad lacks pressure-sensitive hardware sensors, meaning palm rejection must rely on contact area width rather than pressure thresholds.

Launching the Graphical Event Monitor (debug-gui)

For an intuitive visual breakdown of touch contacts, libinput includes a lightweight GTK-based graphical test harness:

sudo libinput debug-gui

The application renders a virtual canvas showing real-time touch points, bounding boxes, finger tracking IDs, and palm rejection exclusion zones as you interact with your trackpad or touchscreen.