{"id":5700,"library":"pynput","title":"pynput","description":"pynput is a Python library that allows you to control and monitor user input devices, specifically the keyboard and mouse. It provides cross-platform functionality for simulating keystrokes and mouse events, as well as listening for input. The current version is 1.8.1, and the library is regularly updated to address platform-specific nuances and improve functionality.","status":"active","version":"1.8.1","language":"en","source_language":"en","source_url":"https://github.com/moses-palmer/pynput","tags":["automation","input","keyboard","mouse","cross-platform","listener","controller"],"install":[{"cmd":"pip install pynput","lang":"bash","label":"Install pynput"}],"dependencies":[{"reason":"Required for pynput to function on Linux using the Xorg backend. Alternatively, uinput requires root privileges.","package":"X server, $DISPLAY environment variable (for Xorg)","optional":false},{"reason":"On macOS, monitoring keyboard input requires the application (or its terminal) to be whitelisted under 'Enable access for assistive devices' in system preferences, or running as root.","package":"Access for Assistive Devices (system setting)","optional":false},{"reason":"pynput leverages the Win32 API for its Windows backend.","package":"Win32 API (system library)","optional":false}],"imports":[{"note":"Commonly imported directly from the top-level package for both monitoring and controlling.","symbol":"keyboard","correct":"from pynput import keyboard"},{"note":"Commonly imported directly from the top-level package for both monitoring and controlling.","symbol":"mouse","correct":"from pynput import mouse"},{"note":"For monitoring keyboard events.","symbol":"Listener (keyboard)","correct":"from pynput.keyboard import Listener"},{"note":"For controlling (sending) keyboard events.","symbol":"Controller (keyboard)","correct":"from pynput.keyboard import Controller"},{"note":"For special keys (e.g., Key.space, Key.enter) when working with keyboard controllers or listeners.","symbol":"Key","correct":"from pynput.keyboard import Key"},{"note":"For monitoring mouse events.","symbol":"Listener (mouse)","correct":"from pynput.mouse import Listener"},{"note":"For controlling (sending) mouse events.","symbol":"Controller (mouse)","correct":"from pynput.mouse import Controller"},{"note":"For mouse buttons (e.g., Button.left, Button.right) when working with mouse controllers or listeners.","symbol":"Button","correct":"from pynput.mouse import Button"}],"quickstart":{"code":"from pynput import keyboard, mouse\nimport time\n\ndef on_press(key):\n    try:\n        print(f'Alphanumeric key pressed: {key.char}')\n    except AttributeError:\n        print(f'Special key pressed: {key}')\n\ndef on_release(key):\n    print(f'Key released: {key}')\n    if key == keyboard.Key.esc:\n        # Stop listener\n        return False\n\n# --- Keyboard Listener ---\nprint(\"Starting keyboard listener. Press 'Esc' to exit.\")\nkeyboard_listener = keyboard.Listener(on_press=on_press, on_release=on_release)\nkeyboard_listener.start()\n\n# --- Mouse Controller (runs after listener starts) ---\nmouse_controller = mouse.Controller()\nprint(f\"Current mouse position: {mouse_controller.position}\")\n\n# Move mouse to (100, 100) and click left button\nmouse_controller.position = (100, 100)\nprint(f\"Moved mouse to: {mouse_controller.position}\")\ntime.sleep(1)\nmouse_controller.click(mouse.Button.left, 1)\nprint(\"Left clicked.\")\n\n# Wait for keyboard listener to stop\nkeyboard_listener.join()\nprint(\"Keyboard listener stopped.\")","lang":"python","description":"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."},"warnings":[{"fix":"Manually grant 'Input Monitoring' permission to your terminal or packaged application in System Settings > Privacy & Security > Accessibility or Input Monitoring.","message":"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.","severity":"breaking","affected_versions":"macOS 10.14 (Mojave) and later"},{"fix":"Dispatch incoming events to a queue and process them in a separate thread, or keep callbacks very short and non-blocking.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions on Windows"},{"fix":"Ensure `$DISPLAY` is correctly set (e.g., `DISPLAY=:0`) or use `uinput` backend with root privileges.","message":"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.","severity":"gotcha","affected_versions":"All versions on Linux (Xorg backend)"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions with IDEs/virtual environments"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}