如何解决pip install网络报错SSLError: TLSV1_ALERT_PROTOCOL_VERSION（OpenSSL过旧）问题

Python系列Bug修复：PyCharm控制台pip install报错 - 如何解决pip install网络报错SSLError: TLSV1_ALERT_PROTOCOL_VERSION（OpenSSL过旧）问题

在使用pip安装Python包时，我们可能会遇到各种各样的错误，其中包括与网络连接和SSL相关的错误。当你在PyCharm控制台使用pip install命令时，遇到如下错误提示：

SSLError: TLSV1_ALERT_PROTOCOL_VERSION

这个问题通常是由于OpenSSL库的版本过旧，无法支持当前Python的TLS协议版本所导致的。本文将详细分析该问题的原因并提供解决方案，帮助你顺利通过pip install过程。

文章目录

• [Python系列Bug修复：PyCharm控制台pip install报错 - 如何解决pip install网络报错SSLError: TLSV1_ALERT_PROTOCOL_VERSION（OpenSSL过旧）问题](#Python系列Bug修复：PyCharm控制台pip install报错 - 如何解决pip install网络报错SSLError: TLSV1_ALERT_PROTOCOL_VERSION（OpenSSL过旧）问题)
• • 一、问题描述与开发场景
  • • [1.1 开发场景](#1.1 开发场景)
    • [1.2 错误的根本原因](#1.2 错误的根本原因)
  • 二、环境介绍
  • • [2.1 开发环境](#2.1 开发环境)
  • 三、解决方案
  • • [3.1 检查OpenSSL版本](#3.1 检查OpenSSL版本)
    • [3.2 更新OpenSSL版本](#3.2 更新OpenSSL版本)
    • [3.3 更新Python环境](#3.3 更新Python环境)
    • [3.4 使用自定义的pip源](#3.4 使用自定义的pip源)
    • • macOS用户的`pip.conf`配置文件
    • [3.5 升级`pip`版本](#3.5 升级pip版本)
    • [3.6 设置环境变量](#3.6 设置环境变量)
    • [3.7 验证SSL/TLS配置](#3.7 验证SSL/TLS配置)
  • 四、总结

一、问题描述与开发场景

1.1 开发场景

在开发Python应用时，尤其是当使用PyCharm作为开发环境并在项目中安装第三方库时，使用pip是最常见的安装方法。pip通常通过HTTPS协议从Python包索引（PyPI）下载并安装所需的包。然而，在一些系统中，可能会遇到如下错误：

SSLError: TLSV1_ALERT_PROTOCOL_VERSION

这个错误提示表明pip无法使用正确的TLS协议进行连接，原因通常是由于系统中的OpenSSL版本过旧，无法支持当前TLS协议的要求。

1.2 错误的根本原因

此问题的根本原因通常与Python在安装时所使用的SSL/TLS库版本相关。SSL/TLS协议是确保数据传输安全的协议，而pip依赖于系统的SSL/TLS库（如OpenSSL）来建立加密连接。如果OpenSSL的版本过旧，则无法支持现代的TLS协议（例如TLSv1.2或TLSv1.3），导致pip无法与PyPI服务器建立安全连接，从而出现SSLError。

二、环境介绍

2.1 开发环境

本文讨论的开发环境为：

• Python版本：Python 3.x
• 操作系统：macOS
• IDE：PyCharm 2025

三、解决方案

3.1 检查OpenSSL版本

首先，我们需要检查系统上安装的OpenSSL版本。你可以通过以下命令来查看当前系统中安装的OpenSSL版本：

openssl version

如果你看到的版本过旧（如1.0.x或更早版本），那么可能就是导致SSLError错误的根本原因。

3.2 更新OpenSSL版本

为了支持现代TLS协议，你需要更新系统中的OpenSSL版本。在macOS上，你可以使用Homebrew来安装或更新OpenSSL：

brew update
brew upgrade openssl

安装完成后，重新检查OpenSSL版本：

openssl version

确保显示的版本是较新的版本（如1.1.x或更高版本）。如果成功更新了OpenSSL版本，尝试再次运行pip install命令。

3.3 更新Python环境

如果你的Python是通过系统的包管理器（如apt或brew）安装的，可能它会捆绑一个旧版本的OpenSSL。为了确保Python使用最新版本的OpenSSL，你可能需要重新安装Python，确保它链接到最新版本的OpenSSL。

在macOS上，可以使用Homebrew重新安装Python：

brew reinstall python

这将确保Python使用更新的OpenSSL版本。

3.4 使用自定义的pip源

如果网络问题依然存在，可以考虑切换到国内的pip镜像源，以提高安装速度并避免连接问题。常用的国内镜像源有清华大学镜像、阿里云镜像等。

编辑或创建pip配置文件，配置为国内镜像源：

macOS用户的pip.conf配置文件

在~/.pip/pip.conf文件中添加如下内容：

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

或者直接使用pip命令行安装时指定镜像源：

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

3.5 升级pip版本

有时候，pip的版本过低也会导致连接问题。可以通过以下命令来升级pip：

pip install --upgrade pip

升级pip后，尝试重新安装包。

3.6 设置环境变量

如果你更新了OpenSSL但Python仍然无法正确识别新的库版本，可能需要设置一些环境变量来指向新的OpenSSL路径。在macOS上，你可以修改~/.bash_profile或~/.zshrc文件来设置环境变量：

export PATH="/usr/local/opt/openssl@1.1/bin:$PATH"
export LDFLAGS="-L/usr/local/opt/openssl@1.1/lib"
export CPPFLAGS="-I/usr/local/opt/openssl@1.1/include"
export PKG_CONFIG_PATH="/usr/local/opt/openssl@1.1/lib/pkgconfig"

然后，运行以下命令使改动生效：

source ~/.bash_profile

3.7 验证SSL/TLS配置

可以通过以下命令验证Python的SSL配置是否正确：

import ssl
print(ssl.OPENSSL_VERSION)

如果输出的是较新的OpenSSL版本（如1.1.x或更高版本），则表示Python已正确使用更新后的OpenSSL版本。

四、总结

SSLError: TLSV1_ALERT_PROTOCOL_VERSION错误通常是由于系统中的OpenSSL版本过旧，导致无法支持现代的TLS协议。通过更新OpenSSL版本、重新安装Python以及升级pip版本，通常可以解决该问题。

在解决此问题时，还可以考虑使用国内镜像源来提高下载速度，并避免网络问题。通过这些方法，你可以顺利地通过pip install安装所需的Python库。

🔔 更多Bug解决方案请查看 ==> 全栈Bug解决方案专栏

---

作者✍️名片