libinput: Quick Start and Common Uses

libinput: Quick Start and Common Uses

libinput is a library and tool for handling input devices on Wayland and X.org. This guide focuses on practical commands you can run to inspect devices, watch events, and visualize input in real time.

Quick-start: what you can do with libinput

  • List all devices recognized by libinput.
  • Print all libinput events as they happen.
  • Visualize events with a GUI.
  • Debug tablet axis values.
  • Display general help.

Basic commands (examples first)

  • List devices
sudo libinput list-devices
  • Print all events
sudo libinput debug-events
  • Show a GUI to visualize events
sudo libinput debug-gui
  • Debug tablet axis values
sudo libinput debug-tablet
  • Show help
libinput {{[-h|--help]}}

Note: Many libinput commands require elevated privileges (sudo) to access input devices. If you run into permissions errors, try prefixing with sudo or adjusting device permissions carefully.

Section 1: List devices

What you’ll see:

  • A summary for each input device libinput detects (name, model, physical/logical capabilities).
  • The device path and a short description

Example output snippet:

Device: a touchpad
  Device path: /dev/input/event2
  GUI: Enabled
  Libinput version: 1.x

Why this is useful: before debugging events, you need to know which devices libinput is handling on your system. This is also a quick sanity check that the devices you expect are present.

Section 2: Observe events in real time

This is the most common workflow when debugging input issues, like a stuck key, a laggy touchpad, or a misbehaving drawing tablet.

Command:

sudo libinput debug-events

What you’ll see:

  • Event types (EV_KEY, EV_REL, EV_ABS, etc.)
  • Source device and timestamp
  • Value changes (e.g., movement, button presses)

Common gotchas:

  • If you don’t see events, you might be reading from the wrong device or you may not have permissions.
  • Some environments buffer events; in a busy session, you may need to filter the output or redirect to a file for later analysis.

Tips:

  • Pipe the output to grep to focus on a device, e.g.:
sudo libinput debug-events | grep -i touchpad

Section 3: Visualize events with a GUI

If you prefer a visual representation, libinput can display a real-time GUI showing touch positions, button presses, and gestures.

Command:

sudo libinput debug-gui

This is handy for tablet work, drawing tests, or verifying that gestures are recognized as intended. If the GUI window doesn’t appear, ensure your session has X/Wayland access and you’re running a compatible compositor.

Section 4: Debug tablets and raw axes

For tablets and drawing devices, axis values can be tricky. libinput provides a focused view for debugging tablet input.

Command:

sudo libinput debug-tablet

What you’ll see:

  • Absolute axis values (X, Y, pressure, tilt)
  • Button presses and tool type

This helps validate pressure curves and directional data when calibrating a stylus.

Section 5: Help and options

If you’re unsure about syntax or available options, libinput can show help:

libinput {{[-h|--help]}}

Common issues and how to resolve them

  • Permission denied when listing devices: run with sudo or add proper udev rules. Be careful editing udev rules; incorrect rules can expose security risks.
  • Missing devices in list-devices: your system may use a different input stack (e.g., some devices are managed by evdev or Wayland-specific layers). Check whether you’re testing on a Wayland session or Xorg and adjust expectations accordingly.
  • GUI not showing: ensure your user has access to the display server and that Wayland/Xorg permissions allow the GUI to capture input events.

Quick troubleshooting checklist

  • Verify privileges: sudo libinput [command].
  • Confirm device presence: libinput list-devices.
  • Check your session: Wayland vs Xorg can affect how libinput surfaces are exposed.
  • Redirect logs if needed: create a file to review later, e.g.:
sudo libinput debug-events > ~/libinput-events.log 2>&1

Summary

libinput provides a focused, practical set of tools for inspecting and debugging input devices on Linux. Start by listing devices, then watch events, and finally use the GUI or tablet debug to isolate issues. With these commands, you can quickly identify misconfigurations, test gesture behavior, and verify that devices are behaving as expected.

See Also