libinput supports some static configuration through udev properties.

These properties are read when the device is initially added to libinput's device list, i.e. before the LIBINPUT_EVENT_DEVICE_ADDED event is generated.

The following udev properties are supported:

LIBINPUT_CALIBRATION_MATRIX

Sets the calibration matrix, see libinput_device_config_calibration_get_default_matrix(). If unset, defaults to the identity matrix.

The udev property is parsed as 6 floating point numbers separated by a single space each (scanf(3) format "%f %f %f %f %f %f"). The 6 values represent the first two rows of the calibration matrix as described in libinput_device_config_calibration_set_matrix().

Example values are:

ENV{LIBINPUT_CALIBRATION_MATRIX}="1 0 0 0 1 0" # default
ENV{LIBINPUT_CALIBRATION_MATRIX}="0 -1 1 1 0 0" # 90 degree clockwise
ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 -1 1" # 180 degree clockwise
ENV{LIBINPUT_CALIBRATION_MATRIX}="0 1 0 -1 0 1" # 270 degree clockwise
ENV{LIBINPUT_CALIBRATION_MATRIX}="-1 0 1 0 1 0" # reflect along y axis

LIBINPUT_DEVICE_GROUP

A string identifying the libinput_device_group for this device. Two devices with the same property value are grouped into the same device group, the value itself is irrelevant otherwise.

LIBINPUT_IGNORE_DEVICE

If set to anything other than "0", the device is ignored by libinput. See Ignoring specific devices for more details.

ID_SEAT

Assigns the physical seat for this device. See libinput_seat_get_physical_name(). Defaults to "seat0".

ID_INPUT

If this property is set, the device is considered an input device. Any device with this property missing will be ignored, see Device type assignment via udev.

ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD, ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK, ID_INPUT_ACCELEROMETER

If any of the above is set, libinput initializes the device as the given type, see Device type assignment via udev. Note that for historical reasons more than one of these may be set at any time, libinput will select only one of these to determine the device type. To ensure libinput selects the correct device type, only set one of them.

WL_SEAT

Assigns the logical seat for this device. See libinput_seat_get_logical_name() context. Defaults to "default".

MOUSE_DPI

HW resolution and sampling frequency of a relative pointer device. See Normalization of relative motion for details.

MOUSE_WHEEL_CLICK_ANGLE

The angle in degrees for each click on a mouse wheel. See libinput_pointer_get_axis_source() for details.

LIBINPUT_MODEL_*

This prefix is reserved as private API, do not use. See Model-specific configuration for details.

LIBINPUT_ATTR_*

This prefix is reserved as private API, do not use. See Model-specific configuration for details.

Below is an example udev rule to assign "seat1" to a device from vendor 0x012a with the model ID of 0x034b.

ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \

ENV{ID_MODEL_ID}=="034b", ENV{ID_SEAT}="seat1"

Device type assignment via udev

libinput requires the ID_INPUT property to be set on a device, otherwise the device will be ignored. In addition, one of ID_INPUT_KEYBOARD, ID_INPUT_KEY, ID_INPUT_MOUSE, ID_INPUT_TOUCHPAD, ID_INPUT_TOUCHSCREEN, ID_INPUT_TABLET, ID_INPUT_JOYSTICK, ID_INPUT_ACCELEROMETER must be set on the device to determine the device type. The usual error handling applies within libinput and a device type label does not guarantee that the device is initialized by libinput. If a device fails to meet the requirements for a device type (e.g. a keyboard labelled as touchpad) the device will not be available through libinput.

Only one device type should be set per device at a type, though libinput can handle some combinations for historical reasons.

Below is an example udev rule to remove an ID_INPUT_TOUCHPAD setting and change it into an ID_INPUT_TABLET setting. This rule would apply for a device with the vendor/model ID of 012a/034b.

ACTION=="add|change", KERNEL=="event[0-9]*", ENV{ID_VENDOR_ID}=="012a", \

ENV{ID_MODEL_ID}=="034b", ENV{ID_INPUT_TOUCHPAD}="", ENV{ID_INPUT_TABLET}="1"

Ignoring specific devices

If a device has the LIBINPUT_IGNORE_DEVICE udev property set to any value but "0", that device is not initialized by libinput. For a context created with libinput_udev_create_context(), the device is silently ignored and never shows up. If the device is added with libinput_path_add_device() to a context created with libinput_path_create_context(), adding the device will fail and return NULL (see that function's documentation for more information).

If the property value is exactly "0", then the property is considered unset and libinput initializes the device normally.

This property should be used for devices that are correctly detected as input devices (see Device type assignment via udev) but that should not be used by libinput. It is recommended that devices that should not be handled as input devices at all unset the ID_INPUT and related properties instead. The LIBINPUT_IGNORE_DEVICE property signals that only libinput should ignore this property but other parts of the stack (if any) should continue treating this device normally.

Model-specific configuration

libinput reserves the property prefixes LIBINPUT_MODEL_ and LIBINPUT_ATTR_ for model-specific configuration. These prefixes are reserved as private API, do not use.

The effect of these properties may be to enable or disable certain features on a specific device or set of devices, to change configuration defaults or any other reason. The effects of setting these properties, the format of the property and the value of the property are subject to change at any time.

Lenovo x220 with touchpad firmware v8.1

The property LIBINPUT_MODEL_LENOVO_X220_TOUCHPAD_FW81 may be set by a user in a local hwdb file. This property designates the touchpad on a Lenovo x220 with a touchpad firmware version 8.1. When this firmware version is installed, the touchpad is imprecise. The touchpad device does not send continuos x/y axis position updates, a behavior also observed on its successor model, the Lenovo x230 which has the same firmware version. If the above property is set, libinput adjusts its behavior to better suit this particular model.

The touchpad firmware version cannot be detected automatically by libinput, local configuration is required to set this property. Refer to the libinput model quirks hwdb for instructions.

This property must not be used for any other purpose, no specific behavior is guaranteed.

Configuring the hwdb

This section outlines how to add an entry to the udev hwdb and reload properties so they are available to libinput.

The hwdb contains a set of match rules that assign udev properties that are available to libinput when the device is connected and/or libinput is initialized. This section only describes the hwdb in relation to libinput, it is not a full documentation on how the hwdb works.

Note: The use of the hwdb by libinput is not part of the public API. It may change at any time. Once tested, changes to the hwdb must be submitted upstream.

Querying the hwdb

libinput only uses device nodes in the form of /dev/input/eventX where X is the number of the specific device. Running libinput debug-events lists all devices currently available to libinput and their event node name:

$> sudo libinput debug-events
-event2   DEVICE_ADDED     Power Button                      seat0 default group1  cap:k
-event5   DEVICE_ADDED     Video Bus                         seat0 default group2  cap:k
-event0   DEVICE_ADDED     Lid Switch                        seat0 default group3  cap:S

...

Note the event node name for your device and translate it into a syspath in the form of /sys/class/input/eventX. This path can be supplied to udevadm info

$> udevadm info
P: /devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
N: input/event0
E: DEVNAME=/dev/input/event0
E: DEVPATH=/devices/LNXSYSTM:00/LNXSYBUS:00/PNP0C0D:00/input/input0/event0
E: ID_INPUT=1
E: ID_INPUT_SWITCH=1
E: MAJOR=13
E: MINOR=64
E: SUBSYSTEM=input
E: TAGS=:power-switch:
E: USEC_INITIALIZED=7167898

Lines starting with E: are udev properties available to libinput. For example, the above device's ID_INPUT_SWITCH property will cause libinput to treat this device as switch device.

Reloading the hwdb

The actual hwdb is stored in binary file on-disk and must be updated manually whenever a .hwdb file changes. This is required both when a user manually edits the .hwdb file but also when the git tree is updated (and that update causes a hwdb change).

To update the binary file on-disk, run:

sudo udevadm hwdb --update

Then, to trigger a reload of all properties on your device, run:

sudo udevadm trigger /sys/class/input/eventX

Then check with udevadm info whether the properties were updated, see Querying the hwdb. If a new property does not appear on the device, use udevadm test to check for error messages by udev and the hwdb (e.g. syntax errors in the udev rules files).

sudo udevadm test /sys/class/input/eventX

Modifying the hwdb

This section applies to users that need to add, change, or remove a hwdb entry for their device. Note that the hwdb is not part of the public API and may change at any time. Once a device has been made to work, the change must be submitted to the libinput bugzilla, see Reporting bugs.

hwdb entries are only applied if a udev rules calls out to the hwdb with the right match format. libinput ships with a set of rules to query the hwdb, the different rules are reflected by their prefix. Again, this is not part of the public API. libinput's matches are composed of a literal "libinput", then either the device name and dmi modalias, or the device types and the input modalias. Any part of the hwdb match line can be a glob by using a literal *. For example:

libinput:keyboard:input:b0011v*
libinput:touchpad:input:b0003v05ACp*
libinput:touchpad:input:b0003v05ACp021A*

This type of matching is the preferred one for any removable device (USB, Bluetooth, ...) that can be uniquely identified by the bustype, vendor and product ID. The first line matches any keyboard device on the serial bus (0x0011). The second line matches any touchpad device with a vendor ID of 0x05AC. The third line matches any touchpad device with a vendor ID of 0x05AC and a product ID of 0x021A. The input:b... string is available in the device's modalias file /sys/class/input/eventX/device/modalias.

In the case of built-in devices that do not have a unique id, we need to use the host system's dmi information. For example:

libinput:name:*Lid Switch*:dmi:*svnLENOVO:*pvrThinkPadT440*

This match applies to any device with a name containing "Led Switch" that is on a Lenovo T440 system. The dmi modalias is available in /sys/class/dmi/id/modalias. For example, on the T440 matched above, the modalias is

dmi:bvnLENOVO:bvrGJET72WW(2.22):bd02/21/2014:svnLENOVO:pn3453453678:pvrThinkPadT440s:rvnLENOVO:rn2012345223:rvrABC123KKK123B:cvnLENOVO:ct10:cvrNotAvailable:

The dmi should always be shortened to the sections that uniquely identify the type system, in this case the vendor (svn) and the product version (pvr). Failing to shorten the system may mean that the hwdb match rule only applies to your specific system, rather than all systems of that type, or that the rule no longer applies after a firmware update.

The hwdb match string is the first portion of the hwdb entry. The second portion is the property to set. Each hwdb entry may match on multiple devices and may apply multiple properties. For example:

libinput:touchpad:input:b0003v05ACp*
  THIS_IS_AN_APPLE_DEVICE=1

libinput:touchpad:input:b0003v05ACp*
libinput:name:*Lid Switch*:dmi:*svnLENOVO:*pvrThinkPadT440*
  FOO=1
  BAR=2

In the example above, any matching touchpad device will have all three properties applied, the lid switch device only has FOO and BAR.

The hwdb does not allow removing properties. Where a property must be unset, it should be set to 0.

Any user-specific hwdb entries should be placed in a file /etc/udev/hwdb.d/99-somename.hwdb. See Reloading the hwdb for instructions on how to reload the hwdb once the file is in place.