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源)
- [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版本：
bash
openssl version如果你看到的版本过旧（如1.0.x或更早版本），那么可能就是导致SSLError错误的根本原因。
3.2 更新OpenSSL版本
为了支持现代TLS协议，你需要更新系统中的OpenSSL版本。在macOS上，你可以使用Homebrew来安装或更新OpenSSL：
bash
brew update
brew upgrade openssl安装完成后，重新检查OpenSSL版本：
bash
openssl version确保显示的版本是较新的版本（如1.1.x或更高版本）。如果成功更新了OpenSSL版本，尝试再次运行pip install命令。
3.3 更新Python环境
如果你的Python是通过系统的包管理器（如apt或brew）安装的，可能它会捆绑一个旧版本的OpenSSL。为了确保Python使用最新版本的OpenSSL，你可能需要重新安装Python，确保它链接到最新版本的OpenSSL。
在macOS上，可以使用Homebrew重新安装Python：
bash
brew reinstall python这将确保Python使用更新的OpenSSL版本。
3.4 使用自定义的pip源
如果网络问题依然存在，可以考虑切换到国内的pip镜像源，以提高安装速度并避免连接问题。常用的国内镜像源有清华大学镜像、阿里云镜像等。
编辑或创建pip配置文件，配置为国内镜像源：
macOS用户的pip.conf配置文件
在~/.pip/pip.conf文件中添加如下内容：
ini
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple或者直接使用pip命令行安装时指定镜像源：
bash
pip install Pillow -i https://pypi.tuna.tsinghua.edu.cn/simple3.5 升级pip版本
有时候，pip的版本过低也会导致连接问题。可以通过以下命令来升级pip：
bash
pip install --upgrade pip升级pip后，尝试重新安装包。
3.6 设置环境变量
如果你更新了OpenSSL但Python仍然无法正确识别新的库版本，可能需要设置一些环境变量来指向新的OpenSSL路径。在macOS上，你可以修改~/.bash_profile或~/.zshrc文件来设置环境变量：
bash
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"然后，运行以下命令使改动生效：
bash
source ~/.bash_profile3.7 验证SSL/TLS配置
可以通过以下命令验证Python的SSL配置是否正确：
python
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解决方案专栏
作者✍️名片
