Raspberry Pi OS下Python keyboard模块行为异常问题求助

云上老周

2026-8-26

问题背景

在搭载Raspberry Pi OS的树莓派设备上安装Python keyboard 模块后，安装流程无异常报错，但调用基础功能时会出现无响应、行为错乱的问题，所有测试程序均通过sudo权限在终端执行，具体异常案例如下：

示例A：运行后无任何输出，不符合预期，keyboard.send函数也存在同类问题，测试代码如下：

import keyboard as kb
kb.write("hello")

示例B：每次运行的输出结果均不相同，运行一段时间后会完全停止工作；预期实现屏蔽按键"1"的原生输出、仅打印自定义提示的功能，测试中print函数可正常运行，测试代码如下：

import keyboard as kb
while True:
    kb.wait("1")
    kb.write("\nYou have pressed the number one!\n")

示例C：可正常回放录制的输入内容，但回放结束后录制的输入内容会被传递到下一个终端提示符，被识别为按下回车后的执行命令，测试代码如下：

import keyboard as kb
recorded = kb.record(until="esc")
kb.play(recorded)

示例D：预期实现仅允许用户输入数字的功能，实际运行时警告信息会重复输出两次；数字输入可正常识别并存入变量最终打印，但会出现异常^[字符，且所有按下的按键都会被传递到下一个终端提示符，测试代码如下：

import keyboard as kb

keystroke = ""
digitstring = ""

while keystroke != "esc":
    keystroke = kb.read_key()

    if keystroke.isdigit() == True:
        digitstring = digitstring + keystroke
        continue
    else:
        print("\nOnly digits allowed!")

print(digitstring)

根因分析与解决方案

这类异常由三个核心问题导致：Raspberry Pi OS输入设备权限配置冲突、Linux终端默认行缓冲与模块全局监听抢占、旧版keyboard模块对新系统libinput适配缺陷，按以下顺序操作即可修复：

修正输入设备权限配置
长期使用sudo运行脚本会导致root用户和当前登录用户的输入监听进程抢占事件资源，是出现输出错乱、事件漏发的核心诱因。先将当前运行用户加入input用户组，获得输入设备的常规访问权限：
```
sudo usermod -aG input $USER
```
执行完成后重启树莓派生效，后续运行相关脚本不需要再加sudo。

关闭终端行规范模式
按键内容泄露到下一个终端提示符、^[转义字符异常、警告信息重复输出的问题，本质是Linux终端默认开启行缓冲（canonical mode），终端本身会缓存按键输入直到回车触发，和keyboard模块的全局事件监听形成双份读取。在脚本最开头加入以下代码，关闭当前终端的行缓冲和输入回显：

import termios
import tty
import sys
import atexit

# 备份终端默认配置
orig_settings = termios.tcgetattr(sys.stdin)
# 设置终端为cbreak模式，关闭行缓冲和回显
tty.setcbreak(sys.stdin.fileno())
# 注册退出钩子，脚本结束时自动恢复终端默认配置，避免后续终端输入异常
atexit.register(lambda: termios.tcsetattr(sys.stdin, termios.TCSADRAIN, orig_settings))

更换适配新系统的模块版本
PyPI源上发布的keyboard模块最后更新于2021年，对基于Debian Bookworm的新版Raspberry Pi OS搭载的高版本libinput存在适配bug，会导致write/send方法无响应、事件重复上报。卸载PyPI上的旧版本，安装项目主线分支的最新代码即可修复该适配问题。
修正代码逻辑缺陷
现有测试代码没有主动拦截原生按键事件，所以按键输入会正常传递到前台终端程序。需要拦截按键时，要在注册监听的参数中开启suppress=True，阻止事件向其他程序传递。以示例B的按键屏蔽逻辑为例，正确写法如下：
```
import keyboard as kb
# 注册热键时开启事件拦截，阻止按键"1"的原生输入传递到终端
kb.add_hotkey("1", lambda: print("\nYou have pressed the number one!\n"), suppress=True)
# 保持脚本运行监听事件
kb.wait()
```
示例D的数字输入限制逻辑同理，需要在读取按键时直接拦截非数字按键的事件传递，不要等读取完成后再做判断——此时事件已经发送给终端，无法再撤回。

内容的提问来源于stack exchange，提问作者seb