Python keyboard模块add_hotkey函数在Windows10上无法正常工作

问题场景 #

运行以下测试脚本时，keyboard.write()功能正常，但add_hotkey、hook_key绑定的触发逻辑完全无响应；相同代码在Linux Mint物理机、Linux虚拟机中均可正常运行，排除硬件键盘问题，锁定为Windows10系统层面问题：

import keyboard

keyboard.write('hehe')
keyboard.add_hotkey('a', lambda: keyboard.write('test'))
keyboard.add_hotkey('ctrl + shift + a', print, args =('input', 'hotkey'))
keyboard.hook_key('q', lambda: print(1))

keyboard.wait()

解决步骤 #

• 以管理员权限执行脚本
  Windows系统的权限机制会限制普通进程捕获全局按键，右键点击Python解释器或脚本文件，选择「以管理员身份运行」后再执行测试代码，这是此类问题最常见的解决方式。

• 排查安全软件拦截
  Windows Defender或第三方杀毒软件可能将keyboard库的按键捕获行为判定为潜在恶意操作（如键盘记录），需进入安全软件的拦截日志，将Python进程或目标脚本加入信任白名单后重试。

• 检查热键冲突
  确认是否有其他后台程序（如AutoHotkey、办公软件、快捷键工具）已占用a、ctrl+shift+a等目标热键，暂时关闭此类程序后重新测试脚本。

• 重装适配Windows的keyboard库
  先卸载现有版本：

  pip uninstall keyboard
  

  再安装最新版以修复可能存在的Windows兼容问题：

  pip install --upgrade keyboard
  

• 优化等待逻辑
  替换原有等待逻辑为带延迟的循环，避免阻塞Windows消息队列：

  import keyboard
  import time
  
  keyboard.write('hehe')
  keyboard.add_hotkey('a', lambda: keyboard.write('test'))
  keyboard.add_hotkey('ctrl + shift + a', print, args=('input', 'hotkey'))
  keyboard.hook_key('q', lambda: print(1))
  
  while True:
      time.sleep(0.1)
  

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