Pip install 报错 SSL 证书验证失败怎么绕过

遇到 pip install 报 SSL 证书验证失败，最稳妥的做法是更换国内镜像源或修复本地 CA 证书，而不是直接禁用验证。

先说结论：禁用证书验证仅是临时止血手段，长期解决应优先切换可信镜像源或更新 certifi 包。

命令速用版

如果只是急于安装包，可以使用以下命令临时跳过验证（注意安全风险）：

pip install `--trusted-host` pypi.org `--trusted-host` files.pythonhosted.org 包名

更推荐的方案是切换镜像源，既快又安全：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名

pip 在安装包时会通过 HTTPS 连接 Python 官方仓库，默认会校验服务器的 SSL 证书。报错通常是因为本地操作系统的 CA 证书库过时、缺失，或者网络环境中存在中间人设备（如公司网关）拦截了 HTTPS 流量并替换了证书。此外，连接官方源网络不稳定也可能导致握手失败。

步骤 1：优先尝试切换镜像源

国内镜像源通常拥有有效的证书且连接更稳定。使用清华大学或阿里云镜像：

pip install -i https://pypi.tuna.tsinghua.edu.cn/simple 包名

步骤 2：临时跳过证书验证（仅限内网或紧急场景）

如果必须连接官方源且无法修复证书，可添加信任主机参数。注意这会让连接暴露于中间人攻击风险：

pip install `--trusted-host` pypi.org `--trusted-host` files.pythonhosted.org 包名

步骤 3：修复本地 CA 证书

尝试升级 certifi 包，它包含了 pip 使用的 CA bundle：

pip install `--upgrade` certifi

如果是 Windows 系统，有时需要手动安装系统根证书更新。

若需永久配置镜像或信任主机，可修改 pip 配置文件。不同系统路径如下：

配置示例（设置镜像源，比跳过验证更安全）：

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple

除了命令行参数，也可以通过设置环境变量来信任主机，适用于脚本或 CI 环境：

Linux/macOS：

export PIP_TRUSTED_HOST="pypi.org files.pythonhosted.org"

Windows (CMD)：

set PIP_TRUSTED_HOST=pypi.org files.pythonhosted.org

设置后再次执行 pip install 即可生效。

执行安装命令后，观察输出日志。成功时会出现 Successfully installed 字样。随后在 Python 交互环境中尝试导入：

python -c "import 包名"

如果没有报错，说明安装成功。同时检查后续安装其他包是否不再报 SSL 错误，以确认环境问题是否根除。

1. 安全风险：长期使用`--trusted-host`或配置 pip 全局跳过验证，会导致下载的被篡改包无法被识别，生产环境严禁这样做。

2. 配置持久化：有人会将跳过验证写入 pip.conf 配置文件，这会导致所有后续安装都处于不安全状态，建议仅在命令行临时使用。

3. 公司网络：如果在公司内网，可能需要配置公司网络网关环境变量，而不是简单跳过 SSL 验证，否则可能无法连接。