This package provides bindings to the generic input event interface in Linux. The evdev interface serves the purpose of passing events generated in the kernel directly to userspace through character devices that are typically located in /dev/input/.

This package also comes with bindings to uinput, the userspace input subsystem. Uinput allows userspace programs to create and handle input devices that can inject events directly into the input subsystem.

In other words, python-evdev allows you to read and write input events on Linux. An event can be a key or button press, a mouse movement or a tap on a touchscreen.

The following GNU/Linux distributions have python-evdev in their package repositories:

The latest stable version of python-evdev can be installed from pypi, provided that you have gcc/clang, pip and the Python and Linux development headers installed on your system. Installing them is distribution specific and typically falls in one of the following categories:

On a Debian compatible OS:

$ apt-get install python-dev python-pip gcc
$ apt-get install linux-headers-$(uname -r)

On a Redhat compatible OS:

$ yum install python-devel python-pip gcc
$ yum install kernel-headers-$(uname -r)

On Arch Linux and derivatives:

$ pacman -S core/linux-api-headers python-pip gcc

Installing python-evdev with pip:

$ sudo pip install evdev

For more advanced installation options, please read the :doc:`full installation <installation>` page.

>>> import evdev

>>> devices = [evdev.InputDevice(fn) for fn in evdev.list_devices()]
>>> for device in devices:
...    print(device.fn, device.name, device.phys)
/dev/input/event1    Dell Dell USB Keyboard   usb-0000:00:12.1-2/input0
/dev/input/event0    Dell USB Optical Mouse   usb-0000:00:12.0-2/input0

>>> import evdev

>>> device = evdev.InputDevice('/dev/input/event1')
>>> print(device)
device /dev/input/event1, name "Dell Dell USB Keyboard", phys "usb-0000:00:12.1-2/input0"

>>> for event in device.read_loop():
...     if event.type == evdev.ecodes.EV_KEY:
...         print(categorize(event))
... # pressing 'a' and holding 'space'
key event at 1337016188.396030, 30 (KEY_A), down
key event at 1337016188.492033, 30 (KEY_A), up
key event at 1337016189.772129, 57 (KEY_SPACE), down
key event at 1337016190.275396, 57 (KEY_SPACE), hold
key event at 1337016190.284160, 57 (KEY_SPACE), up

Python-evdev proudly supports the new async/await syntax in Python 3.5:

import asyncio, evdev

async def print_events(device):
    async for event in device.async_read_loop():
        print(device.fn, evdev.categorize(event), sep=': ')

device = evdev.InputDevice('/dev/input/event4')
asyncio.ensure_future(print_events(device))

loop = asyncio.get_event_loop()
loop.run_forever()

>>> from evdev import ecodes

>>> ecodes.KEY_A, ecodes.ecodes['KEY_A']
... (30, 30)
>>> ecodes.KEY[30]
... 'KEY_A'
>>> ecodes.bytype[ecodes.EV_KEY][30]
... 'KEY_A'
>>> ecodes.KEY[152]  # a single value may correspond to multiple codes
... ['KEY_COFFEE', 'KEY_SCREENLOCK']

The python-evdev package also comes with a small command-line program for listing and monitoring input devices:

$ python -m evdev.evtest

• Read the full :doc:`tutorial <tutorial>`.
• See the example programs.
• Refer to the API :doc:`documentation <apidoc>`:
  • :mod:`device <evdev.device>`
    • :class:`AbsInfo <evdev.device.AbsInfo>`
    • :class:`KbdInfo <evdev.device.KbdInfo>`
    • :class:`InputDevice <evdev.device.InputDevice>`
  • :mod:`events <evdev.events>`
    • :class:`InputEvent <evdev.events.InputEvent>`
    • :class:`KeyEvent <evdev.events.KeyEvent>`
    • :class:`RelEvent <evdev.events.RelEvent>`
    • :class:`AbsEvent <evdev.events.AbsEvent>`
    • :class:`SynEvent <evdev.events.SynEvent>`
  • :mod:`eventio <evdev.eventio>`
    • :class:`EventIO <evdev.eventio.EventIO>`
  • :mod:`eventio_async <evdev.eventio_async>`
    • :class:`EventIO <evdev.eventio_async.EventIO>`
  • :mod:`util <evdev.util>`
    • :class:`list_devices() <evdev.util.list_devices>`
    • :class:`is_device() <evdev.util.is_device>`
    • :class:`categorize() <evdev.util.categorize>`
    • :class:`categorize() <evdev.util.categorize>`
  • :mod:`uinput <evdev.uinput>`
    • :class:`UInput <evdev.uinput.UInput>`
  • :mod:`ecodes <evdev.ecodes>`

Python-evdev exposes most of the more common interfaces defined in the evdev subsystem. Reading and injecting events is well supported and has been tested with nearly all event types.

The basic functionality for reading and uploading force-feedback events is there, but it has not been exercised sufficiently. A major shortcoming of the uinput wrapper is that it does not support force-feedback devices at all (see issue #23).

Some characters, such as : (colon), cannot be easily injected (see issue #7), Translating them into UInput events would require knowing the kernel keyboard translation table, which is beyond the scope of python-evdev. Please look into the following projects if you need more complete or convenient input injection support.

• python-uinput
• uinput-mapper
• PyUserInput (cross-platform, works on the display server level)
• pygame (cross-platform)

Please refer to the :doc:`changelog <changelog>` for a full list of changes.

The :mod:`evdev` package is released under the terms of the Revised BSD License.