keyboard

You can install the keyboard library via PyPI using pip, or by cloning the repository directly. Since it is a pure Python library with zero dependencies, you can also simply copy the source files into your project.

pip install keyboard

When using keyboard.add_hotkey(key, callback), ensure the callback is a function or a lambda. Passing a function call directly (e.g., keyboard.add_hotkey('space', print('pressed'))) will execute the function immediately during registration rather than when the key is pressed.

import keyboard

# DO THIS:
keyboard.add_hotkey('space', lambda: print('space was pressed'))

# OR THIS:
def on_space():
    print('space was pressed')
keyboard.add_hotkey('space', on_space)

When waiting for a key press or a specific state, avoid using busy-wait loops (e.g., while not keyboard.is_pressed('space'): pass) as they will consume 100% of your CPU.

Instead, use keyboard.wait(key) which blocks efficiently, or use keyboard.add_hotkey() to trigger logic via an event callback.

import keyboard

# DO THIS (Efficient):
keyboard.wait('space')
print('space was pressed, continuing...')

# OR THIS (Event-driven):
keyboard.add_hotkey('space', lambda: print('space was pressed!'))
keyboard.wait()

Installs a global listener on all available keyboards. The provided callback is invoked for every key press or release.

The event passed to the callback is a keyboard.KeyboardEvent object with these attributes:

• name: Lower-case Unicode representation of the character (e.g. "&") or description (e.g. "space").
• scan_code: The physical key number (e.g. 55).
• time: Timestamp of the event with OS-provided precision.

Options:

• suppress (bool): If true, prevents the event from being passed to other applications. Defaults to False.
• on_remove (callable): A lambda or function to call when the hook is removed.

Modify keyboard behavior:

• block_key(key): Suppresses all key events for the given key, regardless of modifiers.
• remap_key(src, dst): Whenever src is pressed or released, the hotkey dst is pressed or released instead.
• remap_hotkey(src, dst, suppress=True, trigger_on_release=False): Whenever the hotkey src is pressed, it is suppressed and dst is sent instead.

remap('alt+w', 'ctrl+up')

You can record a sequence of keyboard actions and replay them later using record() and play().

• record(until='escape', suppress=False, trigger_on_release=False): A blocking function that records all keyboard events until the specified until hotkey is pressed. Returns a list of keyboard.KeyboardEvent objects.
• play(events, speed_factor=1.0): Replays a list of events. If speed_factor is <= 0, events are replayed as fast as the OS allows. The current keyboard state is cleared at the start and restored at the end.

Specialized hooks for specific event types:

• on_press(callback, suppress=False): Invokes the callback for every KEY_DOWN event.
• on_release(callback, suppress=False): Invokes the callback for every KEY_UP event.

Sends artificial keyboard events to simulate typing text. Characters not on the keyboard are typed using OS-specific unicode methods (e.g., alt+codepoint).

To ensure integrity, all currently pressed keys are released before typing, and modifiers are restored afterward.

Options:

• delay (float): Seconds to wait between keypresses. Defaults to 0.
• restore_state_after (bool): If true, restores the state of keys that were released at the start. Defaults to True.
• exact (any): If set, forces all characters to be typed as explicit unicode. If None, uses platform-specific suggestions.

Use these functions to clean up listeners:

• unhook(remove): Removes a hook using the callback or the handler returned by hook().
• unhook_all(): Removes all keyboard hooks, including hotkeys, abbreviations, word listeners, recorders, and waits.
• unhook_all_hotkeys(): Removes all keyboard hotkeys, including abbreviations, word listeners, recorders, and waits.