Platform limitations

pynput aims at providing a unified API for all supported platforms. In some cases, however, that is not entirely possible.


On Linux, pynput uses X or uinput.

When running under X, the following must be true:

  • An X server must be running.
  • The environment variable $DISPLAY must be set.

When running under uinput, the following must be true:

  • You must run your script as root, to that is has the required permissions for uinput.

The latter requirement for X means that running pynput over SSH generally will not work. To work around that, make sure to set $DISPLAY:

$ DISPLAY=:0 python -c 'import pynput'

Please note that the value DISPLAY=:0 is just an example. To find the actual value, please launch a terminal application from your desktop environment and issue the command echo $DISPLAY.

When running under Wayland, the X server emulator Xwayland will usually run, providing limited functionality. Notably, you will only receive input events from applications running under this emulator.


Recent versions of macOS restrict monitoring of the keyboard for security reasons. For that reason, one of the following must be true:

  • The process must run as root.
  • Your application must be white listed under Enable access for assistive devices. Note that this might require that you package your application, since otherwise the entire Python installation must be white listed.
  • On versions after Mojave, you may also need to whitelist your terminal application if running your script from a terminal.

Please note that this does not apply to monitoring of the mouse or trackpad.

All listener classes have the additional attribute IS_TRUSTED, which is True if no permissions are lacking.


On Windows, virtual events sent by other processes may not be received. This library takes precautions, however, to dispatch any virtual events generated to all currently running listeners of the current process.

Furthermore, sending key press events will properly propagate to the rest of the system, but the operating system does not consider the buttons to be truly pressed. This means that key press events will not be continuously emitted as when holding down a physical key, and certain key sequences, such as shift pressed while pressing arrow keys, do not work as expected.