Python安装pip时出现SSL错误怎么解决
讲解Python安装或使用pip时出现SSL证书错误的原因与解决方法,包括证书链检查、macOS证书安装、Windows与Linux修复、企业代理证书处理以及最终验证步骤。
Python安装或使用pip时出现SSL错误,通常不是pip本身“安装坏了”,而是Python在通过HTTPS连接PyPI时无法正确验证服务器证书。处理时不要一上来就关闭SSL校验,而应该先确认pip是否已经存在,再检查Python的SSL模块、系统时间、根证书以及代理环境。macOS、Windows、Linux的修复方法有所不同,企业网络还可能需要额外导入内部CA证书。
如果只是Python里没有pip,可以先尝试内置的ensurepip。这个过程本身不需要访问互联网,因此很适合用来区分“pip没有安装”和“HTTPS证书有问题”这两种情况。Python官方文档明确说明,ensurepip使用Python自带的组件完成pip引导安装,不访问互联网。:contentReference[oaicite:0]{index=0}
先看清楚SSL错误到底发生在哪一步
比较常见的报错类似下面这样:
WARNING: Retrying (...) after connection broken by
'SSLError(SSLCertVerificationError(...))'
certificate verify failed: unable to get local issuer certificate
也可能看到:
Could not fetch URL https://pypi.org/simple/...
There was a problem confirming the ssl certificate
还有一种错误比较特殊:
pip is configured with locations that require TLS/SSL,
however the ssl module in Python is not available
前两种说明Python具备SSL能力,但证书验证失败;第三种则说明当前Python根本没有正常加载SSL模块。这两个方向不能用同一种方法解决。
第一步:确认pip到底有没有安装
在终端、PowerShell或命令提示符中执行:
python -m pip --version
macOS或Linux如果系统使用的是python3命令,则执行:
python3 -m pip --version
如果能够看到类似下面的内容,说明pip实际上已经存在:
示例输出:
pip 26.x from .../site-packages/pip (python 3.x)
这时真正失败的通常不是“安装pip”,而是pip访问PyPI、升级pip或下载其他软件包时的HTTPS连接。
如果提示:
No module named pip
可以先使用Python自带的ensurepip:
python -m ensurepip --upgrade
macOS和Linux也可能需要:
python3 -m ensurepip --upgrade
ensurepip不需要访问PyPI,因此即使当前HTTPS证书存在问题,这一步仍然有机会正常完成。:contentReference[oaicite:1]{index=1}
执行成功后,再检查:
python -m pip --version
第二步:确认Python的SSL模块是否正常
证书问题和SSL模块缺失是两件不同的事。先执行:
python -c "import ssl; print(ssl.OPENSSL_VERSION)"
如果能够输出OpenSSL版本,说明Python至少具备SSL支持。接着可以查看Python当前使用的默认证书路径:
python -c "import ssl; print(ssl.get_default_verify_paths())"
如果import ssl本身就报错,例如:
ModuleNotFoundError: No module named '_ssl'
这时不要继续尝试--trusted-host或修改证书文件,因为Python的SSL模块本身没有正确构建。
这种情况比较常见于自行编译的Python。例如编译Python时系统没有安装OpenSSL开发库,就可能导致_ssl模块缺失。最省事的处理方式通常是重新安装来自python.org、系统软件源或可靠包管理器提供的Python。
第三步:先检查系统时间
SSL证书都有有效期。如果电脑日期严重错误,例如系统时间被改到了过去或未来,即使证书本身完全正常,也可能出现“证书尚未生效”或“证书已经过期”的错误。
因此在修改Python之前,先确认操作系统日期、时间和时区正确,并尽量开启自动校时。
如果错误信息中出现下面这些字样,更应该优先检查时间:
certificate has expired
certificate is not yet valid
第四步:macOS使用python.org版本时安装根证书
如果Python是从python.org下载安装的macOS安装包,安装完成后通常还需要执行随Python提供的证书安装脚本。Python官方文档明确要求,安装后可以在对应的Python应用目录中运行Install Certificates.command,它会为该Python安装SSL根证书。:contentReference[oaicite:2]{index=2}
打开Finder,进入类似下面的目录:
/Applications/Python 3.x/
找到:
Install Certificates.command
双击执行即可。
也可以从终端打开。这里的3.x需要替换成电脑中实际存在的版本目录,例如Python 3.14:
open "/Applications/Python 3.14/Install Certificates.command"
官方文档给出的成功标志包括终端中出现类似:
Successfully installed certifi
update complete
完成后关闭并重新打开终端,再测试:
python3 -m pip install requests
Install Certificates.command。不同发行方式使用的Python和证书路径可能不同,应优先按照对应发行工具修复。
第五步:Windows和Linux检查系统CA证书
Windows
普通Windows环境下,如果Python来自官方安装程序,先确认系统时间正确,然后重新测试Python的SSL模块:
python -c "import ssl; print(ssl.OPENSSL_VERSION)"
python -c "import ssl; print(ssl.get_default_verify_paths())"
如果Python安装本身已经损坏,或者是很早以前复制过来的便携环境,重新运行官方Python安装程序进行修复往往比手动复制证书文件更可靠。
如果SSL连接已经恢复,再升级pip:
python -m pip install --upgrade pip
Debian、Ubuntu
Linux发行版通常依赖系统CA证书包。如果证书文件损坏、被误删,或者系统镜像过旧,可以重新安装CA证书:
sudo apt update
sudo apt install --reinstall ca-certificates
sudo update-ca-certificates
完成后重新打开终端,再执行:
python3 -m pip install requests
Rocky Linux、AlmaLinux、RHEL等
sudo dnf reinstall ca-certificates
sudo update-ca-trust
使用较老系统、没有dnf时,可能需要改用:
sudo yum reinstall ca-certificates
sudo update-ca-trust
第六步:公司代理、学校网络和抓包软件要单独处理
如果家庭网络正常,而切换到公司、学校VPN或代理后就出现SSL错误,很可能不是PyPI证书有问题,而是网络中间设备对HTTPS进行了检查。
这类设备可能重新签发网站证书。浏览器因为已经信任公司的内部CA,所以访问网页正常;Python如果不信任这张内部CA,就会出现:
certificate verify failed:
unable to get local issuer certificate
这种情况下,正确做法是向网络管理员取得公司的CA证书,并让pip明确使用它。
假设证书保存为:
/Users/demo/certs/company-ca.pem
可以执行:
python3 -m pip install requests \
--cert /Users/demo/certs/company-ca.pem
Windows示例:
python -m pip install requests --cert C:\certs\company-ca.pem
如果需要在当前终端会话中持续使用,还可以设置pip支持的PIP_CERT环境变量。pip官方文档说明,--cert和PIP_CERT可以指定额外使用的PEM证书包。:contentReference[oaicite:3]{index=3}
macOS或Linux:
export PIP_CERT=/Users/demo/certs/company-ca.pem
Windows PowerShell:
$env:PIP_CERT="C:\certs\company-ca.pem"
然后再执行:
python -m pip install requests
新版pip在受支持的Python版本上能够结合系统证书存储与自身证书进行HTTPS验证,这对企业内部证书环境更友好。不过旧Python、旧pip和特殊发行版的行为可能不同,因此不应只根据系统浏览器“能打开PyPI”就判断Python一定已经信任同一套证书。pip官方文档记录了当前系统证书存储的使用方式及其版本差异。:contentReference[oaicite:4]{index=4}
不建议把--trusted-host当成正式解决方案
网上经常能看到下面这种方法:
python -m pip install requests \
--trusted-host pypi.org \
--trusted-host files.pythonhosted.org
这个参数确实是pip支持的正式参数,作用是把指定主机视为可信主机,即使它没有有效HTTPS验证。:contentReference[oaicite:5]{index=5}
问题在于,它绕过的恰恰是你现在应该修复的证书验证机制。因此它比较适合用来做临时诊断,例如判断“是不是证书验证导致的失败”,而不适合作为长期配置。
--trusted-host以后能够下载,而不加就失败,基本可以把排查重点放到根证书、企业代理、自签名证书或系统证书存储上。确认原因后,应删除这个临时参数并修复证书链。
修复后怎样确认问题真的解决了
不要只以“命令不再显示刚才那一行错误”作为判断标准。可以按下面的顺序验证。
检查SSL模块:
python -c "import ssl; print(ssl.OPENSSL_VERSION)"
检查pip:
python -m pip --version
然后执行一个正常的HTTPS软件包查询或安装。例如:
python -m pip install requests
如果已经安装,可以使用升级检查:
python -m pip install --upgrade requests
正常情况下,pip应该能够连接软件源、读取软件包元数据,并且不再出现SSLCertVerificationError、certificate verify failed等错误。
证书问题解决以后,再升级pip本身:
python -m pip install --upgrade pip
常见错误和对应处理方向
| 报错或现象 | 优先检查 | 处理方向 |
|---|---|---|
No module named pip |
pip尚未安装 | 先执行python -m ensurepip --upgrade |
certificate verify failed |
根证书、系统时间、代理 | 更新或安装可信CA证书 |
unable to get local issuer certificate |
证书链不完整 | 检查系统CA或企业内部CA |
ssl module ... not available |
Python的SSL模块 | 修复或重新安装Python |
| 家庭网络正常,公司网络失败 | HTTPS代理、VPN、内部证书 | 导入公司CA或使用--cert |
使用--trusted-host后正常 |
证书验证链 | 继续查CA问题,不把该参数作为永久方案 |
总结
Python安装pip时遇到SSL错误,最重要的是先判断错误发生在哪一层。如果Python里根本没有pip,可以先用不联网的ensurepip安装;如果pip已经存在,但访问PyPI时出现certificate verify failed,则重点检查系统时间、Python的SSL模块和CA证书。
macOS通过python.org安装Python时,可以优先运行Install Certificates.command;Linux可以检查并重新安装系统ca-certificates;公司代理或HTTPS检查环境则需要让Python信任企业CA证书。只有import ssl本身失败时,才应该把重点转向Python安装或OpenSSL构建问题。
--trusted-host可以用于判断问题是否与证书校验有关,但不宜长期依赖。真正修复后的状态应该是:不绕过SSL验证,pip仍然能够正常通过HTTPS访问PyPI、获取软件包信息并完成下载。
说明:pip官方文档确认其HTTPS连接默认执行证书验证,并支持通过--cert或PIP_CERT指定CA证书包;Python官方文档同时说明macOS的python.org安装包提供证书安装脚本。:contentReference[oaicite:6]{index=6}
免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。









