【BUG已解决】pip install 出现 SSL: CERTIFICATE_VERIFY_FAILED 报错的解决方案前言本文主要介绍了使用 pip 安装 Python 包时出现SSL: CERTIFICATE_VERIFY_FAILED证书验证失败错误的完整排查过程和解决方案涵盖企业网络代理、系统证书缺失、Python证书路径配置、镜像源切换等多种场景希望能帮助大家彻底解决这个困扰众多开发者的经典问题。1. 问题描述1.1 完整报错信息Collecting requests Retrying (Retry(total4, connectNone, readNone, redirectNone, statusNone)) after connection broken by SSLError(SSLCertVerificationError(1, [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006))): /simple/requests/ WARNING: Retrying (Retry(total3, ...)) after connection broken by SSLError(...) ERROR: Could not find a version that satisfies the requirement requests ERROR: No matching distribution found for requestsmacOS 特有的报错形式ssl.SSLCertVerificationError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1002)1.2 具体现象执行pip install 任意包名出现证书验证失败公司网络下更容易出现企业防火墙做了 HTTPS 中间人代理刚安装的 macOS 系统上运行 Python 脚本涉及 HTTPS 请求时报错之前能正常 pip install某次系统更新后突然报错用浏览器访问 pypi.org 是正常的但 pip 命令行报错1.3 触发场景归类场景环境特征企业/学校网络防火墙/安全网关做 SSL 中间人代理macOS 新装 PythonPython.org 官方安装包未正确配置证书系统证书链过期长期未更新系统根证书pip 自身版本过旧旧版 pip 的 SSL 处理逻辑有缺陷VPN/代理软件冲突部分 VPN 软件解密 HTTPS 流量2. 原因分析2.1 SSL 证书验证的基本原理客户端(pip) 发起 HTTPS 请求 ↓ 服务器(pypi.org) 返回证书链 ↓ 客户端验证证书链是否可信 - 查找本地的根证书授权机构(CA)列表 - 验证服务器证书是否由可信CA签发 ↓ 验证通过 → 建立安全连接 → 正常下载 验证失败 → SSL: CERTIFICATE_VERIFY_FAILEDunable to get local issuer certificate这句话的意思是客户端本地找不到能验证服务器证书链的根证书。2.2 五大根本原因#原因说明占比1macOS Python 证书未初始化python.org 官方安装包需要手动运行证书安装脚本30%2企业网络 HTTPS 中间人代理防火墙自签名证书替换了真实证书25%3系统根证书过期/缺失老旧系统长期未更新CA证书库20%4certifi 包版本过旧Python 用的 certifi 证书包没跟上最新CA15%5代理软件解密流量Charles/Fiddler等抓包工具改写了证书10%2.3 macOS 特有问题的根源macOS 从 python.org 下载安装的 Python非系统自带使用的是独立的 SSL 证书体系不会自动使用 macOS 系统的钥匙串证书。安装 Python 后如果没有额外运行证书安装脚本pip 就无法验证任何 HTTPS 网站的证书。3. 解决方案3.1 方案一macOS 运行官方证书安装脚本macOS 专属最常见问题的解法# 找到 Python 安装目录下的证书安装脚本 # 通常在 /Applications/Python 3.x/ 目录下 open /Applications/Python 3.11/Install Certificates.command或者直接在终端运行# 找到当前 Python 版本 python3 --version # 运行对应版本的证书安装脚本路径根据实际版本调整 /Applications/Python\ 3.11/Install\ Certificates.command如果找不到这个文件手动执行等效操作pip install --upgrade certifi python3 -c import certifi; print(certifi.where()) # 输出 certifi 证书文件路径 # 设置 SSL_CERT_FILE 环境变量指向该路径 export SSL_CERT_FILE$(python3 -c import certifi; print(certifi.where())) echo export SSL_CERT_FILE$(python3 -c import certifi; print(certifi.where())) ~/.zshrc source ~/.zshrc3.2 方案二升级 certifi 和 pip 本身# 升级 pip python -m pip install --upgrade pip # 升级 certifi提供最新的根证书列表 pip install --upgrade certifi # 重新尝试安装 pip install requests3.3 方案三使用 --trusted-host 参数临时绕过验证企业网络快速方案pip install requests \ --trusted-host pypi.org \ --trusted-host files.pythonhosted.org \ --trusted-host pypi.python.org永久配置写入 pip 配置文件# 创建/编辑 pip 配置文件 # macOS/Linux: ~/.pip/pip.conf 或 ~/.config/pip/pip.conf # Windows: %APPDATA%\pip\pip.ini mkdir -p ~/.pip cat ~/.pip/pip.conf EOF [global] trusted-host pypi.org files.pythonhosted.org pypi.python.org EOF⚠️ 安全提示--trusted-host会跳过 SSL 证书验证存在安全风险仅建议在可信的企业内网环境临时使用不要在公共网络长期使用此方案。3.4 方案四企业网络配置自定义 CA 证书更安全的企业方案如果你的公司网络使用了 SSL 中间人代理如 Zscaler、Blue Coat正确做法是安装公司提供的根证书# 1. 从 IT 部门获取企业根证书文件通常是 .crt 或 .pem 格式 # 2. 找到 certifi 的证书文件路径 python -c import certifi; print(certifi.where()) # 输出示例: /usr/local/lib/python3.11/site-packages/certifi/cacert.pem # 3. 将企业证书追加到 certifi 的证书包中 cat /path/to/company_ca.crt $(python -c import certifi; print(certifi.where())) # 4. 重新测试 pip install requests3.5 方案五使用国内镜像源同时解决网络慢的问题有些证书问题实际上与访问 pypi.org 的网络环境有关切换到国内镜像可以顺带绕开# 临时使用清华镜像 pip install requests -i https://pypi.tuna.tsinghua.edu.cn/simple # 永久设置镜像源 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple # 其他常用国内镜像 # 阿里云: https://mirrors.aliyun.com/pypi/simple/ # 腾讯云: https://mirrors.cloud.tencent.com/pypi/simple # 豆瓣: https://pypi.doubanio.com/simple/3.6 方案六更新系统根证书Linux# Ubuntu/Debian sudo apt-get update sudo apt-get install --reinstall ca-certificates # CentOS/RHEL sudo yum reinstall ca-certificates sudo update-ca-trust force-enable3.7 方案七Windows 更新系统证书# Windows 通常通过 Windows Update 自动更新根证书 # 手动检查更新 Get-WindowsUpdate # 或者直接安装最新的 Visual C 和 .NET Framework 运行库 # 这些更新通常包含证书库的更新3.8 方案八临时禁用 SSL 验证仅供调试生产环境禁用在 Python 代码内部非 pip 命令行临时禁用import ssl import urllib.request # ⚠️ 仅用于本地调试生产环境切勿使用 ssl._create_default_https_context ssl._create_unverified_context或使用 requests 库import requests # ⚠️ 同样仅用于调试 response requests.get(https://example.com, verifyFalse)4. 排查诊断脚本# diagnose_ssl.py import ssl import certifi import requests print( SSL 诊断报告 ) print(fOpenSSL 版本: {ssl.OPENSSL_VERSION}) print(fcertifi 证书路径: {certifi.where()}) try: response requests.get(https://pypi.org, timeout10) print(f✅ 连接 pypi.org 成功: {response.status_code}) except requests.exceptions.SSLError as e: print(f❌ SSL 验证失败: {e}) except Exception as e: print(f❌ 其他错误: {e}) # 检查证书文件是否存在 import os cert_path certifi.where() if os.path.exists(cert_path): print(f✅ 证书文件存在大小: {os.path.getsize(cert_path)} bytes) else: print(f❌ 证书文件不存在: {cert_path})运行诊断python diagnose_ssl.py6. 排查诊断脚本# diagnose_ssl.py import ssl import certifi import requests print( SSL 诊断报告 ) print(fOpenSSL 版本: {ssl.OPENSSL_VERSION}) print(fcertifi 证书路径: {certifi.where()}) try: response requests.get(https://pypi.org, timeout10) print(f✅ 连接 pypi.org 成功: {response.status_code}) except requests.exceptions.SSLError as e: print(f❌ SSL 验证失败: {e}) except Exception as e: print(f❌ 其他错误: {e}) # 检查证书文件是否存在 import os cert_path certifi.where() if os.path.exists(cert_path): print(f✅ 证书文件存在大小: {os.path.getsize(cert_path)} bytes) else: print(f❌ 证书文件不存在: {cert_path})运行诊断python diagnose_ssl.py7. 各方案适用场景总结方案适用场景安全性推荐度macOS证书脚本macOS python.org安装的Python✅ 安全⭐⭐⭐⭐⭐升级certifi所有场景首选尝试✅ 安全⭐⭐⭐⭐⭐--trusted-host快速临时解决⚠️ 有风险⭐⭐企业CA证书公司内网长期使用✅ 安全⭐⭐⭐⭐国内镜像源同时提速可能绕开证书问题✅ 安全⭐⭐⭐⭐⭐系统证书更新Linux/Windows老系统✅ 安全⭐⭐⭐⭐禁用SSL验证仅调试❌ 危险⭐8. 常见问题 FAQ8.1 conda 环境下的证书问题conda 安装的 Python 使用自己的证书体系与系统 Python 独立# conda 环境下升级证书 conda install -c conda-forge certifi ca-certificates --force-reinstall # 或者用pip方式在conda环境内 pip install --upgrade certifi8.2 requests 库单独配置证书路径如果只是某个 Python 脚本报错而不是 pip 命令本身import requests import certifi # 显式指定使用最新的证书包 response requests.get(https://example.com, verifycertifi.where())8.3 公司内网使用自签名证书的正确姿势# 1. 从系统信任列表导出证书macOS示例 security find-certificate -a -p /Library/Keychains/System.keychain /tmp/system_certs.pem # 2. 追加到 certifi 证书包 cat /tmp/system_certs.pem $(python -c import certifi; print(certifi.where()))8.4 Windows 上 python.org 安装版本 vs Microsoft Store 版本的差异Microsoft Store 版本的 Python 通常直接使用 Windows 系统的证书库很少遇到此问题而 python.org 官方安装包在某些情况下也可能出现类似 macOS 的证书初始化问题# Windows 检查当前使用的证书 python -c import certifi; print(certifi.where()) # 如果证书文件过旧直接升级 pip install --upgrade certifi8.5 VPN 软件导致的证书问题部分 VPN 客户端尤其是企业级VPN会对流量进行深度包检测DPI插入自己的证书# 临时关闭VPN测试是否是VPN导致的问题 # 关闭VPN后重新尝试 pip install pip install requests # 如果关闭VPN后正常说明需要将VPN的证书添加到信任列表9. 总结SSL: CERTIFICATE_VERIFY_FAILED的排查顺序macOS 用户先运行Install Certificates.command所有用户pip install --upgrade certifi企业网络配置--trusted-host或安装企业CA证书顺带提速切换国内镜像源conda用户单独处理conda环境的证书体系VPN用户排查是否是VPN软件的深度包检测导致特别提醒切勿在生产环境或涉及敏感数据传输的场景使用verifyFalse或--trusted-host长期绕过证书验证这会让你的连接暴露在中间人攻击的风险下。
