pynput

Warnings

• breaking macOS Security Permissions: On recent macOS versions, monitoring keyboard input requires explicit user permission via 'Enable access for assistive devices' in System Preferences. Without this, keyboard listeners will not receive events. For scripts run from a terminal, the terminal application itself might need to be whitelisted.
  Fix: Manually grant 'Input Monitoring' permission to your terminal or packaged application in System Settings > Privacy & Security > Accessibility or Input Monitoring.
• gotcha Listener Callbacks and Blocking Operations: Listener callbacks (e.g., `on_press`, `on_move`) are invoked in a separate thread. Performing long-running or blocking operations directly within these callbacks can freeze input for the entire system.
  Fix: Dispatch incoming events to a queue and process them in a separate thread, or keep callbacks very short and non-blocking.
• gotcha Non-blocking Listeners and Program Termination: If a `Listener` is started using `listener.start()` without a subsequent `listener.join()` or keeping the main thread alive, the program may terminate immediately as the main thread exits, stopping the daemon listener thread.
  Fix: Use `listener.join()` to block the main thread until the listener stops, or ensure the main thread has other work to do (e.g., a GUI main loop) to keep the program running.
• gotcha Windows Virtual Key Event Limitations: On Windows, virtual events sent by `pynput.keyboard.Controller` might not always behave identically to physical key presses. Specifically, key press events may not be continuously emitted when 'held down', and complex combinations like Shift + Arrow keys might not work as expected.
  Fix: Test automation scripts thoroughly on Windows, especially for complex key combinations. Consider alternative approaches for continuous key presses if `press()`/`release()` cycles don't suffice.
• gotcha Linux SSH/Remote Execution: Running `pynput` listeners or controllers over SSH without X forwarding or setting the `$DISPLAY` environment variable will generally not work, as it requires an active X server.
  Fix: Ensure `$DISPLAY` is correctly set (e.g., `DISPLAY=:0`) or use `uinput` backend with root privileges.
• gotcha PyCharm/Virtual Environment Issues: Users sometimes report `ImportError` in IDEs like PyCharm even after `pip install pynput`. This is often due to PyCharm's project interpreter not being configured to use the correct Python environment where pynput was installed (e.g., using a project-specific virtual environment instead of global site-packages).
  Fix: Verify that your IDE's project interpreter is configured to use the Python environment where `pynput` was installed. If using a virtual environment, ensure it is activated before installing and running.

Install

• pip install pynput Install pynput

Imports

• keyboard

  from pynput import keyboard

  Commonly imported directly from the top-level package for both monitoring and controlling.
• mouse

  from pynput import mouse

  Commonly imported directly from the top-level package for both monitoring and controlling.
• Listener (keyboard)

  from pynput.keyboard import Listener

  For monitoring keyboard events.
• Controller (keyboard)

  from pynput.keyboard import Controller

  For controlling (sending) keyboard events.
• Key

  from pynput.keyboard import Key

  For special keys (e.g., Key.space, Key.enter) when working with keyboard controllers or listeners.
• Listener (mouse)

  from pynput.mouse import Listener

  For monitoring mouse events.
• Controller (mouse)

  from pynput.mouse import Controller

  For controlling (sending) mouse events.
• Button

  from pynput.mouse import Button

  For mouse buttons (e.g., Button.left, Button.right) when working with mouse controllers or listeners.

Quickstart

This quickstart demonstrates both monitoring keyboard input and controlling mouse actions. A keyboard listener is started in a non-blocking thread, which prints pressed keys until 'Esc' is released. Concurrently, a mouse controller moves the cursor and performs a left-click. The script waits for the keyboard listener to be explicitly stopped by the user.

from pynput import keyboard, mouse
import time

def on_press(key):
    try:
        print(f'Alphanumeric key pressed: {key.char}')
    except AttributeError:
        print(f'Special key pressed: {key}')

def on_release(key):
    print(f'Key released: {key}')
    if key == keyboard.Key.esc:
        # Stop listener
        return False

# --- Keyboard Listener ---
print("Starting keyboard listener. Press 'Esc' to exit.")
keyboard_listener = keyboard.Listener(on_press=on_press, on_release=on_release)
keyboard_listener.start()

# --- Mouse Controller (runs after listener starts) ---
mouse_controller = mouse.Controller()
print(f"Current mouse position: {mouse_controller.position}")

# Move mouse to (100, 100) and click left button
mouse_controller.position = (100, 100)
print(f"Moved mouse to: {mouse_controller.position}")
time.sleep(1)
mouse_controller.click(mouse.Button.left, 1)
print("Left clicked.")

# Wait for keyboard listener to stop
keyboard_listener.join()
print("Keyboard listener stopped.")