{"id":10262,"library":"sshkeyboard","title":"SSH Keyboard Input Capture","description":"sshkeyboard is a small, cross-platform Python library designed for capturing key presses and releases, primarily intended for use within SSH sessions but also functional in local terminal environments. It provides simple callback mechanisms for handling key events, enabling interactive command-line applications. The current version is 2.3.1, with ongoing maintenance for bug fixes and compatibility.","status":"active","version":"2.3.1","language":"en","source_language":"en","source_url":"https://github.com/sshkeyboard/sshkeyboard","tags":["keyboard","input","ssh","terminal","cross-platform","interactive"],"install":[{"cmd":"pip install sshkeyboard","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for the 'until' parameter functionality when sshkeyboard is used in non-SSH (local) environments.","package":"pynput","optional":true}],"imports":[{"symbol":"listen_keyboard","correct":"from sshkeyboard import listen_keyboard"}],"quickstart":{"code":"from sshkeyboard import listen_keyboard\nimport time\n\ndef on_press(key):\n    print(f\"Key '{key}' pressed\")\n\ndef on_release(key):\n    print(f\"Key '{key}' released\")\n\nprint(\"Listening for 5 seconds... Press any key.\")\n# Listens for key presses and releases for a duration of 5 seconds\nlisten_keyboard(on_press=on_press, on_release=on_release, until='5 seconds')\nprint(\"Finished listening.\")","lang":"python","description":"This example demonstrates how to set up `sshkeyboard` to listen for key presses and releases for a specified duration (5 seconds). It defines two callback functions, `on_press` and `on_release`, which are invoked when a key event occurs."},"warnings":[{"fix":"If using `until` locally, install `pynput`: `pip install pynput`.","message":"The `until` parameter in `listen_keyboard` relies on the `pynput` library when running `sshkeyboard` locally (not over SSH). If `pynput` is not installed, the `until` condition might not function as expected, or the program might block indefinitely.","severity":"gotcha","affected_versions":"All versions where `until` is used locally."},{"fix":"Test your application in various target environments. Some terminals may require specific settings or remapping to pass through complex key combinations.","message":"Capturing certain special keys (e.g., function keys, Ctrl+C, Alt+combinations) can be inconsistent across different operating systems and terminal emulators. This is due to variations in how key events are transmitted and interpreted.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Avoid using `sudo` unless absolutely necessary. If elevated privileges are required for other parts of your script, consider running the key listening component as a non-root user or investigating specific `sudo` configuration for terminal input.","message":"Running `sshkeyboard` applications with `sudo` can lead to unexpected behavior, including a complete failure to detect key presses. This often occurs due to privilege separation and differences in how the root environment handles terminal input.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the library using pip: `pip install sshkeyboard`","cause":"The `sshkeyboard` library has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'sshkeyboard'"},{"fix":"Install the optional dependency `pynput`: `pip install pynput`","cause":"When `sshkeyboard` is used outside of an SSH session, the `until` parameter relies on `pynput` for local key detection. `pynput` is likely not installed.","error":"The `until` condition is not stopping the `listen_keyboard` function when running locally."},{"fix":"Try using a different terminal emulator (e.g., Alacritty, Kitty, Windows Terminal, xterm). Ensure your terminal settings are not remapping or consuming these key events. In some cases, configuring `stty` or `terminfo` might be necessary, especially for older SSH servers.","cause":"This is often an issue with the terminal emulator or operating system, which may intercept or interpret special keys differently before `sshkeyboard` can capture them. It's not always a library bug.","error":"Keys are not being detected or unexpected characters are outputted when pressing certain keys (e.g., F1, arrow keys, Ctrl+Shift+C)."}]}