xinput
Configure and list input device settings
TLDR
List all input devices
Disable an input
Enable an input
Disconnect an input from its master
Reattach an input as slave to a master
List settings of an input device
Change a setting of an input device
SYNOPSIS
xinput [options] [device]
xinput {list | list-props | set-prop | set-button-map | enable | disable | test | create-master | remove-master | reattach | set-mode | map-to-output | set-ptr-follower} [arguments]
PARAMETERS
list [--short | --long | --name-only]
Lists all available input devices and their properties. Use --short for a concise list, --long for detailed information, or --name-only to show only device names.
list-props <device>
Lists all properties and their current values for a specified device. Device can be an ID or name.
set-prop <device> <property> <value> [...]
Sets a property for a device to a specified value. Property can be an ID or name.
set-button-map <device> <button1> [<button2> ...]
Sets the button map for a device. Each number in the list represents the logical button corresponding to the physical button.
enable <device>
Enables the specified input device.
disable <device>
Disables the specified input device.
test <device>
Starts a test mode for the device, printing events as they occur. Useful for debugging.
create-master <name>
Creates a new master device (pointer and keyboard) with the specified name. Advanced usage for multi-pointer X.
remove-master <name>
Removes a previously created master device.
reattach <slave> <master>
Reattaches a slave device to a different master device.
set-mode <device> ABSOLUTE|RELATIVE
Sets the operating mode of a device to either absolute (e.g., graphics tablets) or relative (e.g., mice).
map-to-output <device> <output>
Maps a device (typically a graphics tablet) to a specific monitor output, identified by name (e.g., DVI-I-1).
set-ptr-follower <master> <slave>
Makes a slave device follow the pointer of a specified master device. For devices like pen tablets that share the same cursor as the mouse.
--version
Prints the xinput program version and exits.
--help
Prints a summary of command usage and exits.
DESCRIPTION
xinput is a utility to configure and test input devices in the X Window System. It allows users to query properties of input devices (like mice, keyboards, touchpads, graphics tablets), change their settings, and perform various debugging tasks. It interacts with the X Input Extension (XI), providing a command-line interface to manage devices registered with the X server.
Common uses include enabling or disabling touchpads, adjusting mouse sensitivity, remapping buttons, and mapping devices to specific monitor outputs, which is particularly useful for graphic tablets on multi-monitor setups. It's an indispensable tool for customizing the behavior of peripheral devices in a desktop Linux environment, especially when default system settings are insufficient or when troubleshooting device-related issues.
CAVEATS
Settings made with xinput are usually temporary and will be lost upon reboot or X server restart. For persistent configurations, changes must be written to Xorg configuration files, typically in /etc/X11/xorg.conf.d/. Some operations may require root privileges or proper X server permissions. Device names or IDs can change after a reboot, so using device names is often more robust for scripts.
DEVICE IDENTIFICATION
Devices can be identified by their ID number or their name. While IDs are numerical and might change after reboot or hot-plugging, names are usually more stable for scripting and repeated use. Use xinput list to find current IDs and names.
PROPERTIES AND ATOM NAMES
Device properties are identified by names or atom IDs. When setting properties, you can typically use the human-readable property name as listed by xinput list-props. For boolean properties, 0 typically means false/disabled, and 1 means true/enabled.
MASTER AND SLAVE DEVICES (XI2)
The X Input Extension 2 (XI2) introduces the concept of master and slave devices. Master devices are logical pairs (pointer and keyboard) that can have multiple slave devices (physical hardware like a mouse or touchpad) attached to them. This allows for advanced configurations, such as multiple independent cursors on the same screen (Multi-Pointer X).
HISTORY
xinput is part of the X.Org project and has been the primary command-line tool for interacting with the X Input Extension (XI) and its successor, XI2 (X Input 2). XI2 brought significant improvements, including better multi-pointer support, device hot-plugging, and more granular control over input events, making xinput an essential utility for modern X-based desktop environments. It serves as the user-facing component for configuring the input stack that handles various device drivers.