{"id":4598,"library":"keyboard","title":"Keyboard: Global Keyboard Events and Simulation","description":"The `keyboard` library for Python provides full control over the keyboard, allowing users to hook global events, register hotkeys, simulate key presses, and much more. It works on Windows and Linux, with experimental support for macOS. The current version is 0.13.5, and it maintains an active development and release cadence.","status":"active","version":"0.13.5","language":"en","source_language":"en","source_url":"https://github.com/boppreh/keyboard","tags":["keyboard","automation","hotkeys","input","simulation","cross-platform","macros"],"install":[{"cmd":"pip install keyboard","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"keyboard","correct":"import keyboard"}],"quickstart":{"code":"import keyboard\nimport time\n\n# Simulate pressing Shift+S then Space\nkeyboard.press_and_release('shift+s, space')\n\n# Type a sentence\nkeyboard.write('The quick brown fox jumps over the lazy dog.')\n\n# Register a hotkey (Ctrl+Shift+A) to print a message\nkeyboard.add_hotkey('ctrl+shift+a', print, args=('Ctrl+Shift+A triggered',))\n\n# Register a hotkey for a sequence (Page Up then Page Down) to type text\nkeyboard.add_hotkey('page up, page down', lambda: keyboard.write('foobar'))\n\nprint(\"Press Ctrl+Shift+A or Page Up then Page Down. Press 'esc' to exit.\")\n\n# Blocks until 'esc' is pressed\nkeyboard.wait('esc')","lang":"python","description":"This quickstart demonstrates how to simulate key presses, type text, and register complex hotkeys using the `keyboard` library. The program will wait until 'esc' is pressed to terminate."},"warnings":[{"fix":"Run your Python script with `sudo python your_script.py` or configure udev rules for your user to grant access to input devices.","message":"On Linux, the `keyboard` library often requires root privileges (sudo) to access raw keyboard device files, leading to an `ImportError: You must be root to use this library on linux.` if not run with elevated permissions.","severity":"gotcha","affected_versions":"All versions on Linux"},{"fix":"Grant Accessibility permissions via System Preferences/Settings. If issues persist, try running with `sudo` or consider alternative libraries like `pynput` for macOS.","message":"On macOS, `keyboard` support is experimental and requires granting Accessibility permissions to your terminal or IDE. It may also require running with `sudo` for global event hooks. Some users have reported issues with alphanumeric key simulation on certain Python/macOS versions.","severity":"gotcha","affected_versions":"All versions on macOS"},{"fix":"Review logic that relies on raw key names if `get_typed_strings` or event objects are used, and adjust expectations for shifted characters.","message":"Starting from version 0.13.0, event names reported by the library now match the *character typed* rather than the physical key. For example, pressing '1' with Shift will report as '!' instead of '1' for functions like `get_typed_strings`.","severity":"breaking","affected_versions":"0.13.0 and later"},{"fix":"If encountering installation errors around version 0.13.1, use `pip install --no-cache keyboard` to force a fresh download and installation.","message":"Due to a dependency issue in early 0.13.x releases (specifically 0.13.1), users upgrading might encounter installation problems if pip used a cached version.","severity":"gotcha","affected_versions":"0.13.1"},{"fix":"Avoid mixing `keyboard` event handling with `input()`. If interactive input is needed, implement custom input logic solely using `keyboard` functions, or ensure the input methods are not active concurrently.","message":"Mixing `keyboard` with Python's built-in `input()` function or other console input/output libraries can lead to unpredictable behavior or interference, as both attempt to manage input streams independently.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}