LIBINPUT(4)

📦
version 1.5.0 · 5 versions
, in alpine 3.24, arch rolling, debian trixie, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 libinput — the X.Org input driver, bestie edition 💖

okay so this is the manual page for libinput, which lives in section 4 of the Kernel Interfaces Manual. That's your whole header situation. Now sit down, grab a boba, because we're about to make your mouse, keyboard, tablet and touchscreen behave. ✨

🌸 NAME 🌸

libinput — the libinput-based X.Org input driver. That's it, that's the name, she's iconic, she's doing the most. 👑

🦋 SYNOPSIS 🦋

Section "InputDevice"
  Identifier "devname"
  Driver "libinput"
  Option "Device"   "devpath"
  ...
EndSection

literally that's the shape of it. You pop a Section "InputDevice" into your config, give it an Identifier of "devname", point Driver at "libinput", and then start throwing Option lines at it like confetti. 🎀

⭐ NOTE ⭐

not me having to clarify this but — this here is the man page for the X input driver. If what you actually want is the library documentation, you go here instead:

http://wayland.freedesktop.org/libinput/doc/

iykyk 🫶

💜 DESCRIPTION 💜

So. libinput is an Xorg input driver that's based on libinput (yes bestie, the driver is named after the library it's built on, they're matching, it's a whole coordinated outfit 💅). Because of that, it supports every single input device that libinput can handle, and that includes most mice, keyboards, tablets and touchscreens. All of them. In one driver. Slay.

Now here's the tea ☕: it is recommended that you configure your libinput devices through the InputClass directive (go read xorg.conf(5) for that) instead of doing manual per-device configuration. Why? Because devices that you configure inside xorg.conf(5) are not hot-plug capable. Not hot-plug capable!! So your little USB mouse won't just show up when you plug it in. Do not do this to yourself. 😭

✨ CONFIGURATION DETAILS ✨

go read xorg.conf(5) for the general configuration details, and for all the options that work with every input driver, not just this one. This section right here is only covering the stuff that's specific to this driver. Main character energy only. 👑

The following driver Options are supported:

🎀 Options, one by one, no skips 🎀

  • Option "AccelProfile" "string" — sets the pointer acceleration profile to the profile you give it. The permitted values are adaptive, flat, custom. real talk though: not all devices support this option, and not all devices support all of the profiles. If a profile isn't supported, then the default profile for that device gets used instead. Want the full description of the profiles and how they behave? That's in the libinput documentation. 📖
  • Option "AccelSpeed" "float" — sets the pointer acceleration speed, and the range is [-1, 1]. Heads up: this only applies to the flat or adaptive profile. 💨
  • Option "AccelPointsFallback" "string" / Option "AccelPointsMotion" "string" / Option "AccelPointsScroll" "string" — sets the points of the Fallback/Motion/Scroll acceleration functions. The string has to be a space-separated list of floating point non-negative numbers, like for example "0.0 1.0 2.4 2.5". This only applies to the custom profile. Go see the section CUSTOM ACCELERATION PROFILE. 🦋
  • Option "AccelStepFallback" "float" / Option "AccelStepMotion" "float" / Option "AccelStepScroll" "float" — sets the step between the points of the Fallback/Motion/Scroll acceleration functions. When you hand it a step of 0.0, then libinput's Fallback acceleration function is used. This only applies to the custom profile. Again: go see the section CUSTOM ACCELERATION PROFILE. ✨
  • Option "ButtonMapping" "string" — sets the logical button mapping for this device, see XSetPointerMapping(3). The string must be a space-separated list of button mappings, in the order of the logical buttons on the device, and it starts with button 1. The default mapping is "1 2 3 ... 32". A mapping of 0 deactivates the button. Multiple buttons are allowed to have the same mapping, no drama. Invalid mapping strings get discarded and the default mapping is used for all buttons. Buttons that you didn't specify in your mapping just use the default mapping. See section BUTTON MAPPING for more details. 🖱️
  • Option "CalibrationMatrix" "string" — a string of 9 space-separated floating point numbers, in the order "a b c d e f g h i". It sets the calibration matrix to the 3x3 matrix where the first row is (abc), the second row is (def), and the third row is (ghi). Math but make it fashion. 📐
  • Option "ClickMethod" "string" — enables a click method. The permitted values are none, buttonareas, clickfinger. Not all devices support all the methods, so if an option isn't supported, the default click method for that device gets used. 👆
  • Option "DisableWhileTyping" "bool" — says whether the touchpad should be disabled while you're typing on the keyboard. important bestie: this does not apply to modifier keys such as Ctrl or Alt. So you can still hold your modifiers, you just can't get your cursor yeeted mid-sentence. ⌨️
  • Option "Device" "string" — specifies the device through which the device can be accessed. This will generally be in the form "/dev/input/eventX", where X is some integer. When you're using InputClass directives, this option is set by the server, so you don't touch it. The mapping from device node to hardware is system-dependent. Property: "Device Node" (read-only). 🔌
  • Option "DragLockButtons" "L1 B1 L2 B2 ..." — sets "drag lock buttons" that simulate a button logically down even after it's been physically released. To logically release a locked button, you need a second click of the same button.

If the option is a single button number, that button acts as the "meta" locking button for the next button number. See section BUTTON DRAG LOCK for details.

If the option is a list of button number pairs, then the first number of each pair is the lock button, and the second number is the logical button number to be locked. See section BUTTON DRAG LOCK for details.

For both the meta and the button pair configuration, the button numbers are device button numbers, i.e. the ButtonMapping applies after drag lock. 🔒

  • Option "HighResolutionWheelScrolling" "bool" — disables high-resolution wheel scroll events, enabled by default. When it's enabled, the driver forwards only high-resolution wheel scroll events from libinput. When it's disabled, the driver forwards legacy wheel scroll events instead. 🎡
  • Option "HorizontalScrolling" "bool" — enables or disables horizontal scrolling. When it's disabled, this driver will discard any horizontal scroll events from libinput. and no, this does not disable horizontal scroll events from libinput — it merely discards the horizontal axis from any scroll events. Default is enabled. ↔️
  • Option "LeftHanded" "bool" — enables left-handed button orientation, i.e. it swaps the left and right buttons. 🤝
  • Option "MiddleEmulation" "bool" — enables middle button emulation. When it's enabled, pressing the left and right buttons at the same time produces a middle mouse button click. 🖱️
  • Option "NaturalScrolling" "bool" — enables or disables natural scrolling behavior. 🌀
  • Option "RotationAngle" "float" — sets the rotation angle of the device to the angle you give, in degrees clockwise. The angle must be between 0.0 (inclusive) and 360.0 (exclusive). 🔄
  • Option "ScrollButton" "int" — designates a button as the scroll button. If the ScrollMethod is button and the button is logically down, then x/y axis movement gets converted into scroll events. 🔘
  • Option "ScrollButtonLock" "bool" — enables or disables the scroll button lock. If it's enabled, the ScrollButton is considered logically down after the first click and it stays down until the second click of that button. If it's disabled (the default), the ScrollButton button is considered logically down while it's held down, and up once it's physically released. 🔐
  • Option "ScrollMethod" "string" — enables a scroll method. The permitted values are none, twofinger, edge, button. Not all devices support all the options, so if an option isn't supported, the default scroll option for that device gets used. 📜
  • Option "ScrollPixelDistance" "int" — sets the movement distance, in "pixels", that's required to trigger one logical wheel click. This option only applies to the scroll methods twofinger, edge, button. See section SCROLL PIXEL DISTANCE for more details. 📏
  • Option "SendEventsMode" "(disabled|enabled|disabled-on-external-mouse)" — sets the send events mode to disabled, enabled, or "disable when an external mouse is connected". 🚦
  • Option "TabletToolPressureCurve" "x0/y0 x1/y1 x2/y2 x3/y3" — sets the pressure curve for a tablet stylus to the bezier formed by those four points. Each respective x/y coordinate must be in the [0.0, 1.0] range. For more information see section TABLET STYLUS PRESSURE CURVE. ✍️
  • Option "TabletToolPressureRange" "min max" — sets the pressure range for a tablet stylus to the given subset of the physical range. The min/max values must be in the [0.0, 1.0] range. For example, a min of 0.3 means the tablet will send 0 pressure for anything equal to or below 30% of the physical pressure range, and a max of 0.7 means the tablet sends its maximum pressure value for any pressure equal to or higher than 70% of the physical pressure range. 🖊️
  • Option "TabletToolAreaRatio" "w:h" — sets the area ratio for a tablet tool. The area always starts at the origin (0/0) and expands to the largest available area with the aspect ratio you specified. Events outside this area get cropped to the area. The special value "default" is used for the default mapping (i.e. the device-native mapping). For more information see section TABLET TOOL AREA RATIO. 📱
  • Option "Tapping" "bool" — enables or disables tap-to-click behavior. 👆
  • Option "TappingButtonMap" "(lrm|lmr)" — sets the button mapping for 1/2/3-finger taps to left/right/middle or left/middle/right, respectively. 🤞
  • Option "TappingDrag" "bool" — enables or disables drag during tapping behavior ("tap-and-drag"). When it's enabled, a tap followed by a finger held down causes a single button down only, and all motions of that finger thus translate into dragging motion. Tap-and-drag requires the Tapping option to be enabled, so don't skip that one. 🫳
  • Option "TappingDragLock" "bool" — enables or disables drag lock during tapping behavior. When it's enabled, a finger up during tap-and-drag will not immediately release the button. If the finger is set down again within the timeout, then the dragging process continues. ⏳

For all options, the options are only parsed if the device supports that configuration option. For all options, the default value is the one used by libinput. On configuration failure, the default value is applied. periodt. 💅

✨ SUPPORTED PROPERTIES ✨

Okay so here's the tea: libinput serves up all its runtime-configurable options as properties. If one of the properties below isn't showing up, that means the matching config option isn't available on that device — but heads up, that does NOT mean the feature itself is missing from the device. It just means you can't fiddle with it. Anyway, the libinput driver provides these:

  • libinput Accel Profiles Available — 3 boolean values (8 bit, 0 or 1), in order "adaptive", "flat", "custom". Tells you which acceleration profiles this device actually has on tap. 👑
  • libinput Accel Profile Enabled — 3 boolean values (8 bit, 0 or 1), in order "adaptive", "flat", "custom". Tells you which acceleration profile is currently enabled on this device.
  • libinput Accel Speed — 1 32-bit float value, defines the pointer speed. Value range -1, 1. Only applies to the flat or adaptive profile, bestie.
  • libinput Accel Custom Fallback Points, libinput Accel Custom Motion Points, libinput Accel Custom Scroll Points — a space-separated list of 32-bit floating point non-negative numbers, e.g. "0.0 1.0 2.4 2.5". Sets the points of the Fallback/Motion/Scroll acceleration functions. Only applies to the custom profile. Peep the CUSTOM ACCELERATION PROFILE section. 💅
  • libinput Accel Custom Fallback Step, libinput Accel Custom Motion Step, libinput Accel Custom Scroll Step — 1 32-bit float value, sets the step between the points of the Fallback/Motion/Scroll acceleration functions. When a step of 0.0 is provided, libinput's Fallback acceleration function is used instead. Only applies to the custom profile. Again, see CUSTOM ACCELERATION PROFILE.
  • libinput Button Scrolling Button — 1 32-bit value. Sets the button number to use for button scrolling. This setting is independent of the scroll method — to actually enable button scrolling the method must be set to button-scrolling and a valid button must be set.
  • libinput Button Scrolling Button Lock Enabled — 1 boolean value. If true, the scroll button lock is enabled. Also independent of the scroll method and the scroll button, and to enable button scrolling the method must be set to button-scrolling and a valid button must be set. Same energy. 🫶
  • libinput Calibration Matrix — 9 32-bit float values, representing a 3x3 calibration matrix, order is row 1, row 2, row 3.
  • libinput Click Methods Available — 2 boolean values (8 bit, 0 or 1), in order "buttonareas", "clickfinger". Which click methods this device can do.
  • libinput Click Methods Enabled — 2 boolean values (8 bit, 0 or 1), in order "buttonareas", "clickfinger". Which click methods are enabled on this device right now.
  • libinput Drag Lock Buttons — either one 8-bit value specifying the meta drag lock button, or a list of button pairs. See BUTTON DRAG LOCK for the deets.
  • libinput High Resolution Wheel Scroll Enabled — 1 boolean value (8 bit, 0 or 1). Whether high-resolution wheel scroll events are enabled or not.
  • libinput Horizontal Scroll Enabled — 1 boolean value (8 bit, 0 or 1). Whether horizontal scrolling events are enabled or not.
  • libinput Left Handed Enabled — 1 boolean value (8 bit, 0 or 1). Whether left-handed mode is on or off.
  • libinput Middle Emulation Enabled — 1 boolean value (8 bit, 0 or 1). Whether middle emulation is on or off.
  • libinput Natural Scrolling Enabled — 1 boolean value (8 bit, 0 or 1). 1 enables natural scrolling.
  • libinput Rotation Angle — 1 32-bit float value [0.0 to 360.0). Sets the rotation angle of the device, clockwise of its natural neutral position.
  • libinput Scroll Methods Available — 3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge", "button". Which scroll methods this device has.
  • libinput Scroll Method Enabled — 3 boolean values (8 bit, 0 or 1), in order "two-finger", "edge", "button". Which scroll method is currently enabled on this device.
  • libinput Scroll Pixel Distance — 1 32-bit value (nonzero, with additional implementation-defined range checks). Changes the movement distance required to trigger one logical wheel click. 🌀
  • libinput Send Events Modes Available — 2 boolean values (8 bit, 0 or 1), in order "disabled" and "disabled-on-external-mouse". Which send-event modes this device supports.
  • libinput Send Events Mode Enabled — 2 boolean values (8 bit, 0 or 1), in order "disabled" and "disabled-on-external-mouse". Which send-event mode is currently enabled on this device.
  • libinput Tablet Tool Pressurecurve — 4 32-bit float values [0.0 to 1.0]. See TABLET TOOL PRESSURE CURVE.
  • libinput Tablet Tool Area Ratio — 2 32-bit values, corresponding to width and height. Special value 0, 0 resets to the default ratio. See TABLET TOOL AREA RATIO for more.
  • libinput Tapping Enabled — 1 boolean value (8 bit, 0 or 1). 1 enables tapping.
  • libinput Tapping Button Mapping Enabled — 2 boolean value (8 bit, 0 or 1), in order "lrm" and "lmr". Which button mapping is currently enabled on this device.
  • libinput Tapping Drag Lock Enabled — 1 boolean value (8 bit, 0 or 1). 1 enables drag lock during tapping.
  • libinput Disable While Typing Enabled — 1 boolean value (8 bit, 0 or 1). Whether disable-while-typing is on or off.

Most properties have a libinput <property name> Default equivalent that tells you the default value for that setting on this device. 🌈

🎀 BUTTON MAPPING 🎀

X clients receive events with logical button numbers, where 1, 2, 3 are usually interpreted as left, middle, right — and logical buttons 4, 5, 6, 7 are usually interpreted as scroll up, down, left, right. So the fourth and fifth physical buttons on a device will end up sending logical buttons 8 and 9. The ButtonMapping option adjusts the logical button mapping, it does not affect how a physical button is mapped to a logical button. Two different things, don't mix them up bestie.

Back in the day, a device got set to left-handed button mode by applying a button mapping of "3 2 1 ...". But on systems using the libinput Xorg input driver, the recommendation is to use the LeftHanded option instead. Just do that. 💅

Also: the libinput Xorg input driver doesn't use the button mapping after setup. Use XSetPointerMapping(3) to modify the button mapping at runtime. Periodt.

💀 BUTTON DRAG LOCK 💀

Button drag lock holds a button logically down even when the button itself has been physically released since. It comes in two modes:

  • "meta" mode — a meta button click activates drag lock for the next button press of any other button. A button click in the future will keep that button held logically down until a subsequent click of that same button. The meta button events themselves are discarded. And you need a separate meta button click each time you want to activate drag lock for a button in the future. 😮‍💨
  • "pairs" mode — each button can be assigned a target locking button. On button click, the target lock button is held logically down until the next click of the same button. The button events themselves are discarded and only the target button events are sent.
Heads up: this feature is provided by this driver, not by libinput.

🖌️ TABLET TOOL PRESSURECURVE 🖌️

The pressure curve affects how stylus pressure is reported. By default, the hardware pressure is reported as-is. But by setting a pressure curve, the feel of the stylus can be adjusted to be more like, say, a pencil or a brush. Iconic, honestly. ✨

The pressure curve is a cubic Bezier curve, drawn within a normalized range of 0.0 to 1.0 between the four points provided. That normalized range gets applied to the tablet's pressure input so the highest pressure maps to 1.0. The points must have increasing x coordinates — if x0 is larger than 0.0, all pressure values lower than x0 are equivalent to y0. If x3 is less than 1.0, all pressure values higher than x3 are equivalent to y3.

For reference:

  • A linear curve (the default) is "0.0/0.0 0.0/0.0 1.0/1.0 1.0/1.0"
  • A slightly depressed curve (firmer) might be "0.0/0.0 0.05/0.0 1.0/0.95 1.0/1.0"
  • A slightly raised curve (softer) might be "0.0/0.0 0.0/0.05 0.95/1.0 1.0/1.0"
And again: this feature is provided by this driver, not by libinput.

📐 TABLET TOOL AREA RATIO 📐

By default, a tablet tool can access the whole sensor area, and the tablet area is mapped to the available screen area. But for external tablets like the Wacom Intuos series, the height:width ratio of the tablet may be different from that of the monitor — which causes the skew of input data. Not the vibe. 😭

To dodge that skew, an area ratio may be set to match the ratio of the screen device. For example, a ratio of 4:3 will reduce the available area of the tablet to the largest available area with a ratio of 4:3. Events within this area will scale to the tablet's announced axis range, so the area ratio is transparent to the X server. Any events outside this area will send events equal to the maximum value of that axis. The area always starts at the device's origin in its current rotation, i.e. it takes left-handed-ness into account. 🫶

Yes bestie, you guessed it: this feature is provided by this driver, not by libinput.

🌀 SCROLL PIXEL DISTANCE 🌀

So the X server does not support per-pixel scrolling, but it does support smooth scrolling. All scroll events, though, are based around a logical unit of scrolling (traditionally corresponding to a wheel click). Which means you literally cannot scroll by 10 pixels — but a driver can scroll by 1/10th of a logical wheel click. Math is math. 🤓

libinput provides scroll data in pixels. The ScrollPixelDistance option defines the amount of movement equivalent to one wheel click. For example, a value of 50 means the user has to move a finger by 50 pixels to generate one logical click event, and each pixel is 1/50th of a wheel click. Slay. 💖

🔥 CUSTOM ACCELERATION PROFILE 🔥

okay bestie, this one is for the girlies who want to be in charge of their pointer. The custom pointer acceleration profile hands you the keys — full control over how acceleration behaves at every speed. No more vibes-based guessing. 💅

libinput hands you an acceleration function f(x) where:

  • the x-axis is the device speed, measured in device units per millisecond
  • the y-axis is the pointer speed

You define your custom acceleration function using n points, and those points are spaced uniformly along the x-axis, starting from 0 and continuing in constant steps. So the points that define your custom function are:

(0 * step, f[0]), (1 * step, f[1]), ..., ((n-1) * step, f[n-1])

and when a velocity value doesn't land exactly on one of those points? The system calculates a linear interpolation/extrapolation of the two closest points. math girlies, we ate. ✨

There are 3 custom acceleration functions, and each one is used for a different movement type:

  • Fallback — the catch-all default movement type — supported by All devices 🌈
  • Motion — used for pointer motion — supported by All devices 🌈
  • Scroll — used for scroll movement — supported by Mouse, Touchpad 🖱️

Wanna go deeper? (and honestly, same) — the libinput library documentation has more details:

https://wayland.freedesktop.org/libinput/doc/latest/pointer-acceleration.html#the-custom-acceleration-profile

🐛 BUGS 🐛

ngl, there's one thing this driver simply will not do: it does not work with Option "Device" set to an event node in /dev/input/by-id and /dev/input/by-path. like, it just won't. 💀

This can be usually be worked by using Section "InputClass" with an appropriate Match* statement in the xorg.conf(5). (yes, that's exactly how the original says it — "usually be worked" — I don't make the rules, I just pass the tea along. 🫶)

⚠️ real talk: if you're pointing Option "Device" at one of those by-id or by-path event nodes, expect sadness. Go the InputClass route instead.

✨ AUTHORS ✨

Peter Hutterer 👑

👀 SEE ALSO 👀

and that's the whole page, bestie!! 🎀 this was LIBINPUT(4) from the xf86-input-libinput package, version 1.5.0 — periodt. go forth and configure your pointer like the main character you are. 💖🦋🌸

📦 where this page comes from