keyboard

library0.13.5pypypi✓ verified 22d ago

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.

serialization

pip install keyboard

github ↗package ↗

INSTALL

IMPORT

SIG · KEYBOARD

keyboard

serializationpythonv0.13.5

Install

1.6s avg

Import

42ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.13.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.046s · 18.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.6s · import 0.038s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

keyboard

✓ import keyboard

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.

import keyboard import time # Simulate pressing Shift+S then Space keyboard.press_and_release('shift+s, space') # Type a sentence keyboard.write('The quick brown fox jumps over the lazy dog.') # Register a hotkey (Ctrl+Shift+A) to print a message keyboard.add_hotkey('ctrl+shift+a', print, args=('Ctrl+Shift+A triggered',)) # Register a hotkey for a sequence (Page Up then Page Down) to type text keyboard.add_hotkey('page up, page down', lambda: keyboard.write('foobar')) print("Press Ctrl+Shift+A or Page Up then Page Down. Press 'esc' to exit.") # Blocks until 'esc' is pressed keyboard.wait('esc')

Debug

Known issues

gotchaOn 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.

fix

Run your Python script with `sudo python your_script.py` or configure udev rules for your user to grant access to input devices.

affects: All versions on Linux

gotchaOn 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.

fix

Grant Accessibility permissions via System Preferences/Settings. If issues persist, try running with `sudo` or consider alternative libraries like `pynput` for macOS.

affects: All versions on macOS

breakingStarting 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`.

fix

Review logic that relies on raw key names if `get_typed_strings` or event objects are used, and adjust expectations for shifted characters.

affects: 0.13.0 and later

gotchaDue 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.

fix

If encountering installation errors around version 0.13.1, use `pip install --no-cache keyboard` to force a fresh download and installation.

affects: 0.13.1

gotchaMixing `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.

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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'keyboard'

The 'keyboard' package is not installed in the Python environment being used, or there's a typo in the import statement.

fix

Install the package using pip: `pip install keyboard`. Ensure you are installing it into the correct Python environment where your script is being executed.

AttributeError: module 'keyboard' has no attribute 'add_hotkey'

The Python script file itself is named 'keyboard.py', causing a name collision and Python to import the user's file instead of the installed 'keyboard' library.

fix

Rename your Python script file to something other than `keyboard.py` (e.g., `my_script.py`, `key_handler.py`).

OSError: Error 13 - Must be run as administrator

The 'keyboard' library requires elevated privileges (root on Linux/macOS, administrator on Windows) to access low-level keyboard events.

fix

Run your Python script with administrator/root privileges. On Linux/macOS, use `sudo python3 your_script.py`. On Windows, run your terminal or IDE as administrator. On macOS, you may also need to grant 'Accessibility' permissions to your terminal/IDE in System Settings.

keyboard.add_hotkey doesn't work

Hotkeys registered with `keyboard.add_hotkey()` or key detection functions like `keyboard.wait()` or `keyboard.is_pressed()` might not work due to insufficient permissions, conflicts with other applications (like Task Manager on Windows), the Python script exiting prematurely, or other system-level hooks interfering.

fix

Ensure the script is run with administrator/root privileges (e.g., `sudo python3 script.py`). Keep the main program alive (e.g., with `keyboard.wait('esc')` or a persistent loop) so hotkeys remain active. On macOS, grant 'Accessibility' permissions to the terminal or IDE. Investigate and disable conflicting background applications if necessary.

Upgrade

Version history

0.13.5latest on PyPI · released Mar 23, 2020

Audit

Dependencies

No dependency data recorded yet.

Agent activity

25 hits · last 30 days

node

Resources

githubhttps://github.com/boppreh/keyboard ↗

packagehttps://pypi.org/project/keyboard/ ↗