Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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.")
Debug
Known issues
breakingmacOS 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.fixManually grant 'Input Monitoring' permission to your terminal or packaged application in System Settings > Privacy & Security > Accessibility or Input Monitoring.
affects: macOS 10.14 (Mojave) and later
gotchaListener 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.fixDispatch incoming events to a queue and process them in a separate thread, or keep callbacks very short and non-blocking.
affects: All versions
gotchaNon-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.fixUse `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.
affects: All versions
gotchaWindows 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.fixTest automation scripts thoroughly on Windows, especially for complex key combinations. Consider alternative approaches for continuous key presses if `press()`/`release()` cycles don't suffice.
affects: All versions on Windows
gotchaLinux 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.fixEnsure `$DISPLAY` is correctly set (e.g., `DISPLAY=:0`) or use `uinput` backend with root privileges.
affects: All versions on Linux (Xorg backend)
gotchaPyCharm/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).fixVerify 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.
affects: All versions with IDEs/virtual environments
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pynput'
The 'pynput' library is not installed in the Python environment being used, or the IDE/interpreter is configured to use a different Python installation where 'pynput' is not present.
fixInstall the library using pip: `pip install pynput`. If using a virtual environment or an IDE like PyCharm, ensure the correct interpreter with 'pynput' installed is selected.
AttributeError: 'Key' object has no attribute 'char'
This error occurs when attempting to access the `.char` attribute of a 'pynput.keyboard.Key' object (which represents special keys like `Key.space`, `Key.esc`, `Key.shift`), but `.char` is only available for 'pynput.keyboard.KeyCode' objects (alphanumeric keys).
fixUse a `try-except AttributeError` block to handle both `Key` and `KeyCode` types, or check `isinstance(key, pynput.keyboard.KeyCode)` before accessing `.char`. Example: `if hasattr(key, 'char'): print(key.char) else: print(key)`.
AttributeError: module 'pynput.keyboard' has no attribute 'key'
Python is case-sensitive. This error typically arises from trying to refer to special keys using `keyboard.key` (lowercase 'k') instead of the correct `keyboard.Key` (uppercase 'K').
fixEnsure that `Key` is imported and used with an uppercase 'K', e.g., `from pynput.keyboard import Key, Controller` and then `Key.space` or `Key.esc`.
AttributeError: 'str' object has no attribute 'value'
This error often occurs when importing `Controller` from both `pynput.mouse` and `pynput.keyboard` without aliasing, causing the `Controller` name to be overwritten. Subsequent code then calls methods on the wrong `Controller` type or passes incompatible arguments (like a string where a `Button` object is expected).
fixImport `Controller` classes with aliases to differentiate them, e.g., `from pynput.keyboard import Controller as KeyboardController` and `from pynput.mouse import Controller as MouseController`.
Upgrade
Version history
1.8.2latest on PyPI · released May 12, 2026
Audit
Dependencies
X server, $DISPLAY environment variable (for Xorg)requiredRequired for pynput to function on Linux using the Xorg backend. Alternatively, uinput requires root privileges.
Access for Assistive Devices (system setting)requiredOn 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.
Win32 API (system library)requiredpynput leverages the Win32 API for its Windows backend.