Python安装pip时出现SSL错误怎么解决

沈知远
沈知远
发布时间:2026-11-18| 7人浏览过
原创

讲解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模块。这两个方向不能用同一种方法解决。

Python安装pip时出现SSL错误怎么解决
图1:pip出现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。

Python安装pip时出现SSL错误怎么解决
图2:pip通过HTTPS访问PyPI时,证书信任链必须能够完整验证

第三步:先检查系统时间

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
如果你的Python是通过Homebrew、Conda、pyenv或系统软件包安装的,不应机械地去找python.org版本的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
Python安装pip时出现SSL错误怎么解决
图3:不同系统的证书修复入口不同,但目标都是恢复可信CA证书链

第六步:公司代理、学校网络和抓包软件要单独处理

如果家庭网络正常,而切换到公司、学校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
Python安装pip时出现SSL错误怎么解决
图4:处理pip SSL错误时,优先恢复正常证书校验,而不是永久绕过校验

常见错误和对应处理方向

报错或现象 优先检查 处理方向
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}

相关专题:

免责声明:本文内容仅供参考,不代表本站观点。转载或引用请注明出处。

Python 相关产品和应用

全部下载
Selenium

Selenium

4.51.0 · Windows

用于浏览器自动化和 Web 测试的 Python 工具。

scikit-learn

scikit-learn

1.9.1 · Windows

常用 Python 机器学习算法与模型评估工具库。

Black

Black

26.10.1 · Windows

强调一致性的 Python 自动代码格式化工具。

Ruff

Ruff

0.17.1 · macOS

由 Rust 编写的高速 Python 代码检查和格式化工具。

pytest

pytest

9.1.1 · Windows

简洁而强大的 Python 自动化测试框架。

FastAPI

FastAPI

0.146.0 · Windows

高性能 Python API 框架,支持类型提示和自动接口文档。

Flask

Flask

3.1.3 · Windows

轻量灵活的 Python Web 应用框架。

Django

Django

6.1.2 · Windows

成熟的 Python Web 框架,适合构建内容站点和业务系统。

Spyder

Spyder

6.1.7 · Windows

面向科学计算与数据分析的 Python 集成开发环境。

SciPy

SciPy

1.18.1 · Windows

面向科学、工程和技术计算的 Python 算法库。