优先用 pip install --user 或虚拟环境解决权限问题；换清华源加速下载；确保 python 和 pip 指向同一环境；编译型包需安装对应平台构建工具；升级 pip 优先使用 wheel。

pip install 报 EnvironmentError: [Errno 13] Permission denied 怎么办

这是 Windows 或 macOS 上用系统 Python（非虚拟环境）时最常遇到的权限错误。根本原因是 pip 尝试往系统级目录（比如 /usr/local/lib/python3.x/site-packages/ 或 C:\Program Files\PythonXX\Lib\site-packages\）写文件，但当前用户没写入权限。

• 直接加 sudo pip install xxx（macOS/Linux）或以管理员身份运行命令行（Windows）——不推荐，会污染系统 Python，后续升级或卸载易出问题
• 改用 pip install --user xxx：所有包装到当前用户的本地目录（如 ~/.local/lib/python3.x/site-packages/ 或 %APPDATA%\Python\Python3x\site-packages\），无需权限，且不影响他人
• 更稳妥的做法是先创建并激活虚拟环境：python -m venv myenv → source myenv/bin/activate（macOS/Linux）或 myenv\Scripts\activate（Windows），再 pip install —— 这才是现代 Python 开发的标准路径

pip install 时卡在 “Collecting xxx” 或报 ConnectionError / ReadTimeout

本质是 pip 默认源（@#@#@#@#@#@#@#@#@#@0）在国内访问不稳定，DNS 解析慢或连接被重置。

• 临时换国内源安装：pip install -i @#@#@#@#@#@#@#@#@#@1 requests
• 永久配置（推荐）：
  • Windows：在 %APPDATA%\pip\pip.ini 中写入
  • macOS/Linux：在 ~/.pip/pip.conf 中写入
    内容均为：

    [global]
    index-url = https://www.php.cn/link/29ab8937c72f36ca382c32ece8ca5595
    trusted-host = pypi.tuna.tsinghua.edu.cn

• 如果公司内网有私有源，记得加 --trusted-host 参数避免 SSL 验证失败，或用 --cert 指定证书路径

pip install 后 import 失败，提示 ModuleNotFoundError

不是安装失败，而是 Python 解释器和 pip 不是同一个环境。典型场景有：

Webnovel Serial Pipeline

构建并发布在 Quartz 平台上的韩语网络小说连载（草稿→封面→webp→章节 md→lint→发布），使用 Nano Banana Pro + ffmpeg。

下载

• 机器上装了多个 Python 版本（如系统自带 Python 2.7、手动装的 Python 3.9、Anaconda 的 Python），但终端里 python 和 pip 指向不同版本
• VS Code 或 PyCharm 没正确选中解释器，导致编辑器用的是 A 环境，而你在终端用 pip 装到了 B 环境

验证方式：

• 运行 which python（macOS/Linux）或 where python（Windows）
• 运行 which pip 或 where pip
• 对比两者路径是否一致；如果不一致，直接用 python -m pip install xxx，强制用当前 python 对应的 pip

EnvironmentError 出现在 pip install 编译型包（如 numpy、Pillow）时

这类包含 C 扩展，需要本地编译工具链。Windows 上常见报错包含 Microsoft Visual C++ 14.0 is required，macOS 上可能卡在 xcrun: error: invalid active developer path。

• Windows：安装 Microsoft C++ Build Tools，或完整安装 Visual Studio 并勾选“使用 C++ 的桌面开发”
• macOS：运行 xcode-select --install 安装命令行工具；如果已装但失效，先 xcode-select --reset 再重试
• 更省事的办法：优先安装预编译的 wheel 包，避免本地编译——确保 pip 是最新版：python -m pip install --upgrade pip，新版 pip 默认优先拉 wheel

环境变量、PATH、解释器路径、网络源、编译工具——这五个点串起来，基本覆盖了 95% 的 EnvironmentError 场景。真正难的不是报错本身，而是 pip 不告诉你它到底想往哪个路径写、用的是哪个 python、连的是哪台服务器。查清这三点，比盲目重装 pip 有用得多。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！