Mac 终端提示 zsh: command not found: xlwings 并非安装失败，而是 Python 第三方工具的可执行文件未被系统 PATH 识别；根本原因是 Homebrew 或官网安装的 Python 3.12 将 xlwings CLI 工具置于 /Library/Frameworks/Python.framework/Versions/3.12/bin/ 目录下，而该路径未加入 shell 环境变量。
mac 终端提示 `zsh: command not found: xlwings` 并非安装失败，而是 python 第三方工具的可执行文件未被系统 path 识别；根本原因是 homebrew 或官网安装的 python 3.12 将 `xlwings` cli 工具置于 `/library/frameworks/python.framework/versions/3.12/bin/` 目录下，而该路径未加入 shell 环境变量。
xlwings 安装后会向 Python 环境的 bin/ 目录写入一个名为 xlwings 的可执行脚本（本质是 Python 包的 console_scripts 入口），它不同于纯库模块（如 import xlwings），必须通过系统 PATH 才能在终端直接调用。你已确认 pip3 install xlwings 成功，且 Python 脚本能正常导入并操作 Excel——这说明包本身无问题，只是 CLI 工具路径未暴露。
✅ 正确解决步骤（推荐永久生效）
-
确认
xlwings可执行文件真实位置
运行以下命令定位：python3 -m pip show xlwings
查看输出中的
Location:（例如/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages），然后推断其对应bin/目录：ls /Library/Frameworks/Python.framework/Versions/3.12/bin/xlwings # 应返回：/Library/Frameworks/Python.framework/Versions/3.12/bin/xlwings
-
将该目录添加至
PATH（针对 zsh，默认 shell）
编辑~/.zshrc（M1/M2/M3 Mac）或~/.zprofile（若使用 zprofile 管理环境变量）：echo 'export PATH="/Library/Frameworks/Python.framework/Versions/3.12/bin:$PATH"' >> ~/.zshrc source ~/.zshrc
-
验证是否生效
xlwings --version # 应输出类似 0.33.4 xlwings addin install # 后续用于 Excel 插件安装
⚠️ 注意事项：
- 不要使用
sudo ln -sf创建全局软链接（如/usr/local/bin/xlwings），易与 Homebrew 管理冲突，且违反 macOS SIP 安全策略；- 若你使用 VS Code 或 PyCharm，请同步在编辑器中指定 Python 解释器路径（如
/Library/Frameworks/Python.framework/Versions/3.12/bin/python3.12），避免“运行代码”插件仍报command not found；xlwings addin install是启用 Excel VBA 支持的关键命令，必须在 PATH 正确后执行，否则会静默失败——这是 Excel 中RunPython报错的常见前置原因。
? 补充：为什么官方文档未强调此步？
xlwings 官方文档默认假设用户使用的是 Homebrew 安装的 Python（路径为 /opt/homebrew/bin/，已自动纳入 PATH），或虚拟环境（需激活后 bin/ 目录临时生效）。但 macOS 官网 .pkg 安装的 Python 3.12（位于 /Library/Frameworks/）不会自动修改 PATH，这是 Apple 和 Python.org 的明确设计选择，旨在避免多版本冲突。因此，手动追加 bin/ 路径是合规、安全且必需的操作。
完成上述配置后，你即可在终端自由使用全部 xlwings CLI 功能（如 xlwings quickstart、xlwings runpython、xlwings addin install），并与 Excel 深度集成，无需重启系统或重装任何组件。
