PyAutoGUI 0.9.26离线安装实战：依赖配置与pyscreeze报错排查

简介PyAutoGUI 0.9.26 是一款面向 Python 开发者的跨平台 GUI 自动化控制库安装包适用于需要模拟鼠标键盘操作、完成界面自动化测试、数据采集或重复性桌面任务的初中级开发者。该库支持 Windows、macOS 与 Linux通过 move_to、click、write 等函数即可快速实现脚本化控制并配有屏幕截图定位与热键触发能力。压缩包共 37 个文件以 Python 源码py、RST 文档rst、文本说明txt及包元信息pkg-info为主其中 py 文件为核心库实现与测试脚本rst 文件为官方文档与使用教程整体仅 53KB轻量易部署。目前已有 468 人学习下载。资源包内除完整库文件外还包含 setup.py、README 与详尽的 docs 文档以及 basicTests.py 等测试用例便于读者理解库结构、快速集成到项目中并参照官方示例开展自动化实践。 拿回一个 PyAutoGUI-0.9.26.zip大部分人的场景其实都一样要么是公司内网装不了最新依赖要么是从旧项目归档里翻出来这个包手头又没有安装文档只能硬着头皮把这个 zip 变成可用的 Python 自动化环境。PyAutoGUI 0.9.26 虽然发布有些年头了但它恰好是整个 PyAutoGUI 生态里最常被当作“基准版本”的一个压缩包网上大量教程贴的代码在这个版本上能跑很多老自动化脚本也是按这套 API 写的。这篇文章就围绕这个 zip 包展开——它到底怎么装、怎么用、以及那个几乎所有人都会撞上的报错pyautogui was unable to import pyscreeze该怎么解。1. 为什么这个旧版本至今还在被翻出来用1.1 0.9.26 在 PyAutoGUI 版本序列里的位置PyAutoGUI 0.9.26 属于项目从“能用但粗糙”走向“方法名稳定”的关键过渡版本。今天你在网上搜到的大多数 PyAutoGUI 中文教程代码风格在 0.9.26 上基本都是直接可跑的moveTo、click、typewrite、hotkey、locateOnScreen这些核心函数从这一版开始就已经确定了签名后面很多年没有大改。换句话说你用 0.9.26 学到的用法换到新版本上依然成立反过来新版本文档里写的基础内容在 0.9.26 里也能复现。这正是很多老项目舍不得升级它的原因——API 稳定行为和文档匹配不需要为“升级”而升级。但也不要把它理解成一个“功能残缺”的老古董。0.9.26 已经内置了鼠标控制、键盘输入、剪贴板交互、截屏和图像识别定位这套完整能力只是图像识别部分依赖它内部调用的 pyscreeze 库而 pyscreeze 又依赖 Pillow。后面很多版本做的事情更多是修复第三方依赖的兼容性而不是增加新的底层能力。所以你在 0.9.26 上遇到的问题大概率不是“这个版本太老缺少某功能”而是“依赖没配对导致某个功能调用失败”。1.2 离线包与内网部署的现实需求为什么会出现 PyAutoGUI-0.9.26.zip 这种文件而不是直接用pip install pyautogui我接触过不少这种情况归纳起来基本是三类需求内网环境无法访问 PyPI 镜像只能通过 U 盘或内部共享目录把源码包拷进去解压后本地安装项目被锁定了依赖版本比如某套自动化测试脚本当年就是用 0.9.26 写的为了保证行为一致性后续新增的执行机也必须装同款版本某些老旧 Python 环境比如 Python 3.6/3.7 的嵌入式解释器装不了最新版 PyAutoGUI反而 0.9.26 能顺利跑起来。这类场景里zip 源码包是最通用的交付形式。它比 wheel 包更能让部署者看清依赖关系也比直接丢一个.py文件更接近“完整项目”的形态。所以接到手之后别急着解压跑setup.py先理清楚它依赖了什么、你的环境缺什么再动手能省掉后面一大半的排错时间。2. 安装之前先把依赖理顺pyscreeze、Pillow 和系统权限2.1 从 zip 安装的完整流程先把 zip 解压到本地目录正常情况下你会看到一个包含setup.py、pyautogui文件夹以及一堆文档的目录结构。进入该目录后最省事的方式是用 pip 直接指定目录安装cd PyAutoGUI-0.9.26 pip install .如果你是在没有外网的机器上操作并且已经提前准备了所有依赖包也可以用经典方式python setup.py install两种方式本质相同都是把pyautogui包拷贝进当前 Python 环境的 site-packages。区别在于pip install .会尝试从网络解析依赖而setup.py install不会自动拉依赖你必须在执行前手动把pyscreeze、pymsgbox、pytweening、mouseinfo、pygetwindow、pyrect、Pillow这些包全部装齐。否则安装完 PyAutoGUI 之后一调高级功能就会报错。2.2 不同平台的隐藏依赖PyAutoGUI 是一个跨平台库但它在三个主流平台上的底层依赖完全不一样。最容易忽略的就是这一点平台额外系统依赖说明Windows无直接可用靠 win32 API 实现控制macOS辅助功能权限系统设置里要给终端/Python 进程授权否则部分键鼠操作无效Linuxscrot截图功能依赖scrot命令未安装时screenshot()会报错我实际用下来macOS 的权限问题最隐蔽。PyAutoGUI 不报“导入失败”而是静默不起作用——鼠标移动了但界面没反应或者键盘输入发不出去。这种情况去“系统设置 - 隐私与安全性 - 辅助功能”里勾选对应的终端或 Python 进程即可。Linux 则是scrot缺失在 Ubuntu/Debian 上执行sudo apt install scrotCentOS 上对应的包名是scrot用 yum/dnf 装就行。2.3 用三段命令验证环境是否真的就绪装完别急着写业务脚本先用三个命令把地基夯实。第一段确认 PyAutoGUI 版本第二段确认图像识别依赖第三段确认截图能力python -c import pyautogui; print(pyautogui.__version__) python -c import pyscreeze; print(pyscreeze ok) python -c import pyautogui; pyautogui.screenshot(test.png); print(screenshot ok)如果第一段输出了0.9.26说明主体安装没问题第二段没报错说明 pyscreeze 和 Pillow 都在第三段成功生成test.png说明截图链路通了。这三段全部通过之后再往下写自动化逻辑就基本不会遇到环境层面的幺蛾子。我在不少新环境里测试过90% 的安装问题都会在第二段命令暴露出来——这正是后面第四部分要展开的经典报错。3. 常用 API 与真实自动化场景3.1 点击、输入、快捷键最基础的三个动作PyAutoGUI 的核心价值是把“人工在桌面上做的操作”翻译成代码。一个最典型的初始化配置我建议你每次写脚本都带上import pyautogui import time pyautogui.PAUSE 0.5 pyautogui.FAILSAFE TruePAUSE是每次键鼠操作之间的固定间隔单位秒。默认值是 0.1对现代电脑来说太快容易漏操作我习惯设置成 0.3 到 0.5。FAILSAFE是 PyAutoGUI 的“保险栓”打开后脚本运行期间你把鼠标猛地甩到屏幕左上角(0, 0)它会立刻抛出FailSafeException中止程序。这个设计非常救命——自动化脚本一旦失控你最快的中断方式不是切终端按 CtrlC而是甩鼠标。接下来是三个最高频的动作# 移动并点击 pyautogui.moveTo(100, 200, duration0.3) pyautogui.click(300, 400) # 带间隔的键盘输入 pyautogui.typewrite(hello world, interval0.05) # 组合快捷键 pyautogui.hotkey(ctrl, s)移动鼠标时加duration参数别用瞬移因为有些软件会检测瞬时大距离跳变。输入中文比较麻烦typewrite只支持 ASCII 字符遇到中文我一般先复制到剪贴板再用pyautogui.hotkey(ctrl, v)粘贴然后pyautogui.press(enter)确认。3.2 弹窗兜底与无人值守日常办公里最消耗耐心的不是填表本身而是填到一半跳出个系统弹窗。用 PyAutoGUI 做无人值守脚本时我通常会在主流程里加一个“弹窗拦截”逻辑定期截屏找特定按钮图标找到就点击然后回到主流程继续跑。import pyautogui if pyautogui.locateOnScreen(confirm_btn.png): pyautogui.click(pyautogui.center(pyautogui.locateOnScreen(confirm_btn.png)))这段代码的含义是先在屏幕上查找confirm_btn.png这个按钮的截图像提前用截图工具剪下来的小图找到后计算它的中心位置并点击。配上while True循环就能实现一个简单的“值守逻辑”。不过要提醒一点这种写法里每个locateOnScreen都是一次全屏截屏 图像匹配相当消耗 CPU。如果业务窗口固定不变建议用region参数限定搜索范围这个在第五部分细讲。3.3 图像识别定位从找图到点图locateOnScreen是 PyAutoGUI 图像识别家族里最常用的函数它背后依赖 pyscreeze。除了locateOnScreen还有几个兄弟函数很有用locateCenterOnScreen(image)直接返回目标中心坐标省一步center()locateAllOnScreen(image)返回所有匹配位置的生成器适合同一图标出现在多处、需要逐个处理的场景locateOnScreen(image, grayscaleTrue)先把图像转成灰度再匹配速度约能提升 30%但颜色相近的图标容易误匹配。举个例子一个表格系统里每行数据都带“删除”按钮我想把所有行都处理一遍import pyautogui for pos in pyautogui.locateAllOnScreen(del_btn.png, confidence0.8): x, y pyautogui.center(pos) pyautogui.click(x, y)这个脚本会从左到右、从上到下扫描屏幕找到所有匹配“删除”按钮图标的位置并点击。用confidence0.8表示允许 80% 的相似度即可匹配缓解图标尺寸略有差异导致找不到的问题。4. 全网高频报错实录pyautogui was unable to import pyscreeze4.1 这个报错出现的条件你搜 PyAutoGUI 教程时一定会看到这条报错因为它实在太经典了pyautogui was unable to import pyscreeze. (this is likely because youre running a version of python that is not supported by pyscreeze. try upgrading pyscreeze to the latest version)很多人一开始很困惑安装 PyAutoGUI 时明明没有报错怎么调用locateOnScreen就炸了原因在于 PyAutoGUI 源码里pyscreeze不是启动时就导入的而是延迟到图像识别相关函数内部才执行import pyscreeze。也就是说只用鼠标键盘功能完全没问题一旦遇到“找图”“截图”导入动作才触发这时如果环境里没有 pyscreeze 或 pyscreeze 自身导入失败就会抛出这条提示。这个“延迟导入”的设计本意是好的让只使用键鼠功能的用户不必安装 Pillow 等重量级依赖。副作用就是报错信息被劫持成了 PEP 式的英文提示真正的异常原因被吞掉了。4.2 我的排查链路遇到这条报错别按表面提示直接去升级 Python 版本那是治标不治本。我建议按下面的顺序排查第一步先确认pyscreeze到底装没装pip show pyscreeze输出里能看到版本号和安装路径说明装上了如果提示WARNING: Package(s) not found那问题就很直接装一下就行。第二步单独导入试一次把真实异常暴露出来python -c import pyscreeze这一步是关键。PyAutoGUI 把异常包装成了友好提示但 pyscreeze 自己报的错误是原始的。如果这里出现ModuleNotFoundError: No module named PIL说明工程里还缺 Pillow如果出现AttributeError: module PIL.Image has no attribute ANTIALIAS说明 pyscreeze 版本太老跟新版 Pillow 不兼容。第三步检查 Python 版本和 pyscreeze 版本的匹配度。老版本 pyscreeze、Pillow 与 Python 3.9、Pillow 10 的组合经常出冲突。修复方式是把依赖升到兼容版本pip install --upgrade pyscreeze pillow第四步也是很多人忽略的确认你安装装的当前环境就是你运行脚本的环境。特别是机器上同时存在多个 Python 时系统 Python、Anaconda、虚拟环境、嵌入式解释器pip install默认装进了某个环境而运行脚本用的可能是另一个。用which python和python -m pip show pyscreeze这两条命令对齐一下。第五步以上都正常还是报错把site-packages里pyscreeze目录删掉重新pip install pyscreeze。有时候历史残留的.pyc缓存文件会造成诡异问题重装能清掉。4.3 根因归类与预防把网上能看到的同类报错整理一遍根因其实逃不出下面几张表原因类别具体表现解决方法依赖缺失pyscreeze 未安装或 Pillow 未安装pip install pyscreeze pillow版本冲突pyscreeze 过旧Pillow 过新导入时代码不兼容pip install --upgrade pyscreezePython 版本过新Python 3.12 上老 pyscreeze 部分 API 失效升级 pyscreeze或换 Python 3.10/3.11环境错乱多个 Python 环境包装错位置which pythonpip show对齐环境预防措施就一条给每个自动化项目建独立的虚拟环境不要往系统 Python 里塞包。比如python -m venv auto_env source auto_env/bin/activate # Windows 下执行 auto_env\Scripts\activate pip install pyautogui0.9.26 pyscreeze pillow虚拟环境隔离了依赖冲突即使玩坏了删掉重建也就一分钟的事比在系统环境里排查半天舒服得多。5. 识别精度与运行速度的平衡技巧5.1 confidence 背后的 opencv 依赖用locateOnScreen时加confidence0.8确实能降低误匹配率但很多人不知道这个参数依赖 OpenCV。如果你没安装opencv-python一加confidence就会看到报错confidence keyword requires opencv解决方式很简单pip install opencv-python装完 OpenCV 后PyAutoGUI 会用它替换默认的纯 Python 图像匹配算法匹配速度会变慢一些因为要算特征但匹配精度明显提升。我的经验是如果只是找固定位置的固定图标完全可以不用confidence默认的像素级匹配更快如果图标在不同窗口状态下有细微明暗变化或者需要容忍缩放再考虑confidence0.8以上的值。低于 0.8 的相似度反而容易误匹配到其他相似元素调参时要小心。5.2 region 裁剪把搜索范围缩小十倍全屏找图是最耗时的操作。一张 1920x1080 的截图上做匹配每次可能要几百毫秒到几秒不等。如果界面结构固定把搜索范围缩小到指定区域速度提升非常明显import pyautogui region (0, 150, 800, 500) icon_pos pyautogui.locateCenterOnScreen(toolbar_icon.png, regionregion) pyautogui.click(icon_pos)region参数接收(x, y, width, height)四元组表示从屏幕左上角(x, y)开始宽度和高度内的区域。注意这里的x, y是区域左上角坐标不是中心点。我把一个原本全屏搜索需要 1.2 秒的脚本裁到固定工具栏区域后耗时降到 0.3 秒左右循环跑几十次差距非常明显。截取找图用的模板图也很关键。看起来一样的图标在屏幕上的实际截图可能和用画图工具抠出来的图有细微色差。我一般用 PyAutoGUI 自带的截图功能直接截取目标区域存成模板import pyautogui pyautogui.screenshot(my_icon.png, region(100, 100, 30, 30))这样截出来的图和运行时截屏的颜色空间完全一致匹配成功率最高。5.3 DPI 缩放与多屏坐标的实战处理坐标对不齐是 PyAutoGUI 新手最容易遇到、又最难自己查明白的问题。最典型的就是 Windows 系统把显示缩放设置为 125% 或 150% 时系统截图分辨率是 1920x1080但 PyAutoGUI 内部拿到的是物理像素坐标可能是 2560x1440结果鼠标点到了另一个位置。解决办法是在脚本开头调用系统 API 关闭 DPI 感知差异import ctypes ctypes.windll.user32.SetProcessDPIAware() import pyautogui注意要在导入 pyautogui 之前调用否则已缓存的屏幕尺寸可能仍是缩放后的。macOS 的 Retina 屏也会遇到类似问题PyAutoGUI 官方建议在 Retina 屏上使用时测量坐标仅供参考必要时通过pyautogui.size()拿到的窗口尺寸与实际截图尺寸做换算。多显示器扩展模式是另一个坑。Windows 扩展模式下副屏坐标可能是负数副屏在左侧时PyAutoGUI 对负坐标支持不完整某些版本上点击行为会异常。我的实践是把副屏设置为主屏再跑脚本或者在代码里写成“先切换到主屏操作再处理副屏”。另外不同显示器缩放比例不同时跨屏移动鼠标的坐标换算特别容易出错这种场景我一般干脆放弃 PyAutoGUI 的纯坐标改用图像识别定位因为图标位置不会因为坐标换算而漂移。从实际维护角度看PyAutoGUI 0.9.26 这套环境配齐 pyscreeze、Pillow 和 OpenCV 之后应付常规办公自动化绰绰有余。我自己写自动化脚本的习惯是先开一个只有标题栏的空窗口把脚本读秒跑一遍看鼠标动作是否按预期移动确认无误再切换到真实业务界面。千万别一上来就对正式系统执行否则一个click点错位置轻则误操作重则可能把弹窗点成“删除”。最后再提醒一句自动化跑太久之后记得在脚本里写清楚日志记录每一步点击的坐标和结果这能帮你定位究竟是脚本逻辑出问题还是界面上某个按钮位置变了。本文还有配套的精品资源点击获取