症状:课程要求安装 requests,但终端提示 pip: command not found,或者 pip 显示的是旧版本。
最快解法:先查 Python 3.14 的解释器路径和 pip 归属,再用它创建 venv,全程通过 python -m pip 安装。多数情况不需要重装 Python,也不应先用 sudo 强行写入全局目录。

这篇文章适合已经安装 Python 3.14,却遇到 pip 找不到、权限拒绝、externally-managed-environment、SSL 证书失败或软件包构建失败的学生。学校电脑没有管理员权限,或你正在使用远程 Mac 学习 Python,也可以按下面的顺序排查。

先确认解释器与 pip 的真实指向

失败案例:Python 已安装,pip 却属于旧环境

假设你刚安装了 Python 3.14,输入:

python3.14 --version

终端显示 Python 3.14,但接着输入:

pip --version

结果却指向另一套旧 Python,甚至直接提示找不到命令。这是因为同一台 Mac 可以同时存在系统工具、旧版 Python、官方安装器版本和项目自己的虚拟环境。

把它想成一排教室:python3.14 是你要进入的教室,pip 是发教材的工具。如果教材管理员属于另一间教室,安装看似成功,课程代码仍然可能找不到包。

先运行:

python3.14 --version
python3.14 -m pip --version
which python3.14
which pip

重点看第 2 行。它应当显示 pip 的版本,以及对应 Python 3.14 安装目录下的路径。官方文档也推荐使用 python -m pip,因为这种写法会明确指定由当前解释器加载 pip,而不是依赖 PATH 中碰巧排在前面的 pip 命令。可参考 Python 3.14 的模块安装说明pip 命令文档

观察结果 更可能的原因 低风险动作
python3.14 有版本,pip 找不到 pip 脚本不在 PATH,或命令名不同 使用 python3.14 -m pip
pip --version 指向旧目录 多套 Python 并存 不使用裸 pip,改用版本化解释器
python3.14 -m pip 也失败 pip 缺失或安装不完整 先检查 ensurepip,不要下载陌生脚本
安装后代码仍无法导入 编辑器或项目使用了另一解释器 检查 venv 路径和编辑器解释器

macOS 自带的 /usr/bin/python3 可能属于 Apple 的开发工具,不能把它当成你刚安装的 Python 3.14。Python 官方 macOS 文档也提醒,不要修改或删除 Apple 控制的那套 Python;不同安装路径之间还可能因为 PATH 顺序产生混淆。可查看 Python 在 macOS 上的官方说明

用当前解释器建立独立 venv

三种“pip 不工作”不是同一件事

你需要先区分现象:

  • 没有 pippython3.14 -m pip --version 报找不到模块。
  • pip 文件存在但不能运行:能看到路径,却出现权限或启动错误。
  • Shell 找不到 pippip --version 失败,但 python3.14 -m pip --version 正常。

课程项目最稳妥的处理方式,是先建立一个独立的 venv。官方文档说明,venv 会使用创建它的那套 Python,并把项目依赖与基础环境隔离开。具体步骤可参考 Python venv 官方文档

在课程项目目录中执行:

cd ~/你的课程项目
python3.14 -m venv .venv
source .venv/bin/activate

激活后,终端提示符通常会出现 (.venv)。然后确认:

python --version
python -c "import sys; print(sys.executable)"
python -m pip --version

此时 python 应显示 Python 3.14,sys.executable 应指向当前项目里的 .venv/bin/python。不要只看提示符,因为虚拟环境也可以不激活,直接调用它的完整路径。

安装课程依赖时使用:

python -m pip install requests

退出环境:

deactivate

下次继续课程时,在项目目录重新执行:

source .venv/bin/activate

每个项目是否都要单独创建 venv?如果课程依赖不同,建议每个项目一个。这样项目 A 升级某个包时,不会把项目 B 的环境一起改掉。虚拟环境可以删除后重建,课程代码不应放进 .venv 文件夹。

pip 缺失时的恢复顺序

如果 Python 3.14 确实存在,但下面命令失败:

python3.14 -m pip --version

先尝试查看 pip 是否能由当前 Python 自带的 ensurepip 恢复:

python3.14 -m ensurepip --default-pip
python3.14 -m pip --version

ensurepip 使用 Python 自带组件,不需要从网络下载 pip。官方文档说明,它主要用于安装时跳过 pip,或 pip 后来被移除的情况。可查看 ensurepip 官方说明

如果你已经创建了 .venv,更建议删除并重建,而不是修改全局 Python:

rm -rf .venv
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip --version

只有当你确认课程目录无误、里面没有需要保留的环境文件时,才执行删除命令。不要删除 /usr/bin/Library/Frameworks 或学校统一管理的目录。

处理权限错误与 externally-managed-environment

把全局 Python 当作公共教室

出现以下提示时,不要马上加 sudo

Permission denied
externally-managed-environment

全局 Python 像学校的公共教室。管理员维护其中的工具,学生项目不应直接改动。externally-managed-environment 的含义是:当前 Python 被标记为外部管理,安装工具应引导你使用虚拟环境,而不是修改默认安装位置。相关规则见 Python Packaging 的外部管理环境规范

推荐动作:

mkdir -p ~/python-course/demo
cd ~/python-course/demo
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install requests

不推荐把下面这些作为新手默认方案:

  • sudo pip install ...
  • ❌ 修改受保护的系统目录权限。
  • ❌ 强行突破外部管理标记。
  • ❌ 为了安装一个包而覆盖学校设备策略。
  • ❌ 在网上复制来源不明的修复脚本。

如果学校电脑允许运行 Python,但不允许全局安装,你仍可能在自己的项目目录使用 venv。若连创建目录、启动终端或访问软件包索引都被策略阻止,就不要尝试绕过限制。把报错截图和课程要求交给老师或管理员,或者使用已获授权的远程 Mac。

提醒: sudo 可能让一次安装暂时成功,但它没有解决“pip 属于哪套 Python”或“软件包是否兼容”的问题。课程环境被写乱后,下一次导入失败往往更难定位。

排查证书、网络与软件包构建

SSL 错误不一定是 pip 的问题

常见错误包括:

CERTIFICATE_VERIFY_FAILED
Could not fetch URL
Temporary failure in name resolution
ProxyError

它们对应的方向不同:

错误线索 先观察什么 合规处理
CERTIFICATE_VERIFY_FAILED 是否使用官方 Python 安装器,证书步骤是否完成 检查安装器提供的证书安装程序
ProxyError 学校网络是否要求代理 按学校说明配置,不猜代理地址
域名解析失败 浏览器能否打开软件包索引页面 换到允许访问的网络验证
临时连接失败 同一命令是否偶尔成功 稍后重试,保留完整错误信息

Python 官方 macOS 文档说明,官方安装器提供 Install Certificates.command,用于安装该 Python 使用的 SSL 根证书。安装 Python 3.14 后,如果应用程序文件夹里有对应的证书安装程序,应从官方安装目录启动它,再重新尝试安装。

不要使用 --trusted-host、关闭 SSL 校验,或复制陌生证书文件来“绕过”错误。如果你使用的是学校 Wi-Fi,先用浏览器确认网络是否需要登录页面。再执行:

python -c "import ssl; print(ssl.OPENSSL_VERSION)"
python -m pip install requests -v

-v 只用于收集更完整的日志。它不能修复网络,但能帮助你区分证书、代理和解析错误。

“没有匹配版本”与 Apple Silicon 构建失败

如果错误类似:

No matching distribution found
Failed building wheel
Could not build wheels

不要立刻判断为 pip 损坏。可能原因有:

  • 软件包尚未发布支持 Python 3.14 的版本。
  • 当前包只提供某些 Python 版本的 wheel。
  • Apple Silicon 与 Intel 的平台标签不匹配。
  • 课程指定的包版本与当前 Python 版本冲突。
  • pip 找不到成品 wheel,只能尝试本地源码构建。

wheel 可以理解为“已经装订好的教材”,下载后通常不需要你现场编译。没有合适的 wheel 时,pip 可能下载源码分发包,再在本机生成 wheel;这时就可能需要编译器、系统库或软件包自己的构建工具。可参考 Python Packaging 关于软件包格式的说明

先查询软件包官方发布页和 PyPI 元数据,重点核对:

  • 是否有 Python 3.14 对应的版本。
  • 是否有 macOS 和当前 CPU 架构的 wheel。
  • 课程是否允许使用较早的兼容版本。
  • 软件包文档是否要求特定编译工具。

wheel 文件名中的 Python、ABI 和平台标签用于表达兼容范围;不能因为另一个软件包支持 Python 3.14,就推断所有包都支持。具体标签规则可查看 Python Packaging 的二进制分发格式说明

当前设备适合继续修复的条件:

  • ✅ 官方发布页明确支持 Python 3.14。
  • ✅ 存在匹配当前 Mac 架构的 wheel。
  • ✅ 课程允许安装所需的构建工具。
  • ✅ 你有权限完成安装。

满足不了时,先使用课程明确支持的 Python 版本,或暂时换到干净环境验证项目。不要为了一个包在学校电脑上安装未经批准的编译器。

完成编辑器与课程项目验收

终端成功,不代表 VS Code 已经成功

你可能在终端里看到:

Successfully installed ...

但在编辑器中运行代码仍然出现:

ModuleNotFoundError: No module named ...

这通常意味着编辑器选择了另一套 Python。安装位置正确,不等于编辑器自动选中了正确环境。

在已经激活 .venv 的终端中执行:

python -m pip show requests
python -c "import requests; print(requests.__file__)"
python -c "import sys; print(sys.executable)"

再在编辑器中选择项目目录下的:

.venv/bin/python

最后创建一个最小测试文件:

import requests

print("import successful")
print(requests.__version__)

如果终端和编辑器都能运行,才算课程环境真正接通。不要反复安装同一个包来解决解释器选择问题。

你也可以参考 Python 3.14 首次配置相关教程;如果学校设备权限限制明显,可先了解 远程 Mac 的可用方案,重点看交付方式和你是否能在其中创建项目环境。

新手故障验收清单

按顺序勾选。任何一项失败,都先停在这一层,不要跳到重装系统。

  • [ ] python3.14 --version 显示课程要求的 Python 版本。
  • [ ] python3.14 -m pip --version 能显示 pip 版本与路径。
  • [ ] pip 路径属于当前 Python 3.14,而不是旧环境。
  • [ ] 项目目录中已经创建 .venv
  • [ ] 激活后,python -c "import sys; print(sys.executable)" 指向 .venv
  • [ ] 使用 python -m pip install 包名 完成安装。
  • [ ] python -m pip show 包名 能显示安装位置。
  • [ ] 最小 import 测试成功。
  • [ ] 编辑器选择的是同一个 .venv/bin/python
  • [ ] 退出终端后,重新进入项目仍能通过 source .venv/bin/activate 恢复环境。
  • [ ] 课程依赖已记录到 requirements.txt 或课程指定的依赖文件中。

如果只剩某个包无法安装,问题已经从“pip 故障”缩小为“软件包兼容性或构建条件”。此时查包的官方记录,比继续重装 Python 更有效。

多数学生继续使用现有设备就够了:能运行 Python 3.14、能创建 venv、网络允许下载依赖,课程项目就可以正常进行。只有在学校设备禁止终端操作、旧环境残留无法清理、证书配置受管理策略阻止,或课程截止时间临近而关键包始终无法构建时,才建议切换环境。

如果你当前的电脑属于学校统一管理设备,反复用 sudo、修改受保护目录和关闭证书校验,只会把问题从一个项目扩大到整台电脑。相较之下,MACCOME 的远程 Mac 更适合用来先验证一份干净的课程环境:你可以从解释器路径开始,创建 venv,安装依赖,再完成 import 验收。它不替代长期本地开发,也不适合需要物理接口或持续高负载的场景;但对临时赶课程、验证 Python 3.14 兼容性,或学校电脑权限受限的学生,先用一台可控环境跑通项目,通常比继续破坏原设备更稳妥。