简介：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 进程授权，否则部分键鼠操作无效 |
| Linux | scrot | 截图功能依赖scrot命令，未安装时screenshot()会报错 |
我实际用下来，macOS 的权限问题最隐蔽。PyAutoGUI 不报“导入失败”，而是静默不起作用——鼠标移动了但界面没反应，或者键盘输入发不出去。这种情况去“系统设置 -> 隐私与安全性 -> 辅助功能”里勾选对应的终端或 Python 进程即可。Linux 则是scrot缺失，在 Ubuntu/Debian 上执行sudo apt install scrot，CentOS 上对应的包名是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中止程序。这个设计非常救命——自动化脚本一旦失控，你最快的中断方式不是切终端按 Ctrl+C，而是甩鼠标。
接下来是三个最高频的动作：
# 移动并点击 pyautogui.moveTo(100, 200, duration=0.3) pyautogui.click(300, 400) # 带间隔的键盘输入 pyautogui.typewrite('hello world', interval=0.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, grayscale=True)：先把图像转成灰度再匹配，速度约能提升 30%，但颜色相近的图标容易误匹配。
举个例子，一个表格系统里每行数据都带“删除”按钮，我想把所有行都处理一遍：
import pyautogui for pos in pyautogui.locateAllOnScreen('del_btn.png', confidence=0.8): x, y = pyautogui.center(pos) pyautogui.click(x, y)这个脚本会从左到右、从上到下扫描屏幕，找到所有匹配“删除”按钮图标的位置并点击。用confidence=0.8表示允许 80% 的相似度即可匹配，缓解图标尺寸略有差异导致找不到的问题。
4. 全网高频报错实录：pyautogui was unable to import pyscreeze
4.1 这个报错出现的条件
你搜 PyAutoGUI 教程时一定会看到这条报错，因为它实在太经典了：
pyautogui was unable to import pyscreeze. (this is likely because you're 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 pyscreeze |
| Python 版本过新 | Python 3.12+ 上老 pyscreeze 部分 API 失效 | 升级 pyscreeze，或换 Python 3.10/3.11 |
| 环境错乱 | 多个 Python 环境，包装错位置 | which python+pip show对齐环境 |
预防措施就一条：给每个自动化项目建独立的虚拟环境，不要往系统 Python 里塞包。比如：
python -m venv auto_env source auto_env/bin/activate # Windows 下执行 auto_env\Scripts\activate pip install pyautogui==0.9.26 pyscreeze pillow虚拟环境隔离了依赖冲突，即使玩坏了删掉重建也就一分钟的事，比在系统环境里排查半天舒服得多。
5. 识别精度与运行速度的平衡技巧
5.1 confidence 背后的 opencv 依赖
用locateOnScreen时加confidence=0.8确实能降低误匹配率，但很多人不知道，这个参数依赖 OpenCV。如果你没安装opencv-python，一加confidence就会看到报错：
confidence keyword requires opencv解决方式很简单：
pip install opencv-python装完 OpenCV 后，PyAutoGUI 会用它替换默认的纯 Python 图像匹配算法，匹配速度会变慢一些（因为要算特征），但匹配精度明显提升。我的经验是：如果只是找固定位置的固定图标，完全可以不用confidence，默认的像素级匹配更快；如果图标在不同窗口状态下有细微明暗变化，或者需要容忍缩放，再考虑confidence=0.8以上的值。低于 0.8 的相似度反而容易误匹配到其他相似元素，调参时要小心。
5.2 region 裁剪：把搜索范围缩小十倍
全屏找图是最耗时的操作。一张 1920x1080 的截图上做匹配，每次可能要几百毫秒到几秒不等。如果界面结构固定，把搜索范围缩小到指定区域，速度提升非常明显：
import pyautogui region = (0, 150, 800, 500) icon_pos = pyautogui.locateCenterOnScreen('toolbar_icon.png', region=region) 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点错位置，轻则误操作，重则可能把弹窗点成“删除”。最后再提醒一句，自动化跑太久之后，记得在脚本里写清楚日志，记录每一步点击的坐标和结果，这能帮你定位究竟是脚本逻辑出问题，还是界面上某个按钮位置变了。
本文还有配套的精品资源，点击获取
