sshkeyboard

What it is and what it does

sshkeyboard is a keyboard event callback library designed to work in environments where traditional keyboard libraries fail—specifically SSH sessions, headless servers, and WSL. It reads keyboard input from stdin on Unix systems (using fcntl and termios) and from msvcrt on Windows, then fires on_press and on_release callbacks for each key. It supports both synchronous and asynchronous callbacks, sequential or concurrent execution modes, and can be controlled via asyncio.

The trade-off is significant: it cannot detect modifier keys (Ctrl, Shift, Alt, Super, Caps Lock), does not reliably handle multiple simultaneous key presses, and may lose input during rapid key spam. These limitations are inherent to reading from stdin rather than using system-level input APIs. The library is useful for simple remote control scenarios—like steering a Raspberry Pi robot over SSH—but not for applications requiring full keyboard state or complex key combinations.

Use it for:

• Control a Raspberry Pi robot or RC car remotely over SSH by mapping key presses to motor commands.
• Build a headless server application that responds to keyboard input without X server or uinput.
• Create a simple terminal-based game or interactive tool that runs inside WSL 2 or a remote terminal.
• Monitor or debug a system via SSH with keyboard-driven callbacks for quick actions.
• Prototype keyboard-driven automation on systems where other keyboard libraries do not work.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Captures keyboard input via callbacks in SSH sessions and headless environments without requiring X server, uinput, or root access.

Yes, if you need keyboard input in an SSH session or headless environment and can accept the limitations (no modifier keys, no simultaneous multi-key presses). The library is stable, dependency-free, and permissively licensed. Maintenance is dormant but the codebase relies only on standard library, so breakage is unlikely. Not suitable for applications requiring full keyboard state or complex key combinations.

Install

sshkeyboard on PyPI

pip install sshkeyboard

uv add sshkeyboard

poetry add sshkeyboard

Installing sshkeyboard

Before you install

Low friction: pure Python wheel with no runtime dependencies. Maintenance is dormant—last commit 2024-07-24—but the codebase is stable and uses only standard library modules (fcntl, termios on Unix; msvcrt on Windows).

License in practice

Licensed under MIT (permissive), so you can use, modify, and distribute freely with minimal restrictions.

Quickstart

pip install sshkeyboard

from sshkeyboard import listen_keyboard

def press(key):
    print(f"'{key}' pressed")

listen_keyboard(on_press=press)

Requires Python 3.6+. On Unix systems, keyboard input is read from stdin; on Windows, uses msvcrt. Some modifier keys (Ctrl, Shift, Alt, Super) do not register, and holding multiple keys simultaneously does not work reliably.

Verify before relying

• Whether Windows support (noted as 'still new') has matured since the last release in October 2021.
• Real-world reliability of key timing parameters (delay_second_char, delay_other_chars) across different terminal emulators and SSH clients.
• Whether the library handles rapid key presses without losing input in production scenarios.

Package facts

Evidence: sshkeyboard-2.3.1-py3-none-any.whl

Keywords: keyboard, listener, ssh, callback, headless, wsl, wsl2, server, x server, uinput, Raspberry Pi, pynput

Tags

More Python Modules packages