urllib3 与 OpenSSL 的兼容性问题

问题描述

当在 macOS 环境下安装 openai 库后尝试导入时，出现如下错误：

python

ImportError: urllib3 v2.0 only supports OpenSSL 1.1.1+, 
currently the 'ssl' module is compiled with LibreSSL 2.8.3

完整错误堆栈如下：

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  ...
  File ".../urllib3/__init__.py", line 38, in <module>
    raise ImportError(
ImportError: urllib3 v2.0 only supports OpenSSL 1.1.1+...

错误的核心原因是：

urllib3 v2.0+ 要求系统有 OpenSSL 1.1.1+ 的支持
macOS 默认使用 LibreSSL 编译 Python 的 ssl 模块
两个组件不兼容导致导入失败

注意事项

即使执行 pip install --upgrade urllib3 也无效，因为系统环境问题与库版本无关

解决方案

🔧 方法一：降级 urllib3（推荐）

适用场景：需要快速解决问题且不依赖 urllib3 v2.0 的新特性

bash

# 卸载当前版本
pip uninstall urllib3

# 安装兼容旧版本（任选其一）
pip install 'urllib3<2.0'         # 安装最新 1.x 版本
pip install urllib3==1.26.6       # 安装特定兼容版本

验证是否解决

重新运行 Python 并导入 openai 应不再报错

python

import openai  # 正常执行无错误

方法二：升级 Python 版本

适用场景：系统允许安装新版本 Python（推荐升级至 Python 3.11+）

bash

# 使用 Homebrew 安装最新 Python
brew install python@3.12

# 创建新虚拟环境
python3.12 -m venv myenv
source myenv/bin/activate

# 重新安装依赖
pip install -r requirements.txt

优势

新版 Python 默认链接 OpenSSL 1.1.1+，一劳永逸解决问题

⚙️ 方法三：手动编译 OpenSSL

适用场景：必须保持当前 Python 版本（如需要兼容性）

bash

# 下载编译 OpenSSL
wget https://www.openssl.org/source/openssl-1.1.1d.tar.gz
tar -xzf openssl-1.1.1d.tar.gz
cd openssl-1.1.1d/
./config --prefix=/custom/openssl/path
make
make install

# 重新编译 Python 并链接 OpenSSL
CONFIGURE_OPTS="--with-openssl=/custom/openssl/path" pyenv install 3.9.6

验证 OpenSSL 版本：

python

>>> import ssl
>>> print(ssl.OPENSSL_VERSION_INFO)
(1, 1, 1, 11, 15)  # 正确版本应为 1.1.1+

❌ 不推荐的"解决方案"

以下方式可能隐藏问题但无法真正解决：

忽略警告（不处理安全隐患）

python

import warnings
warnings.filterwarnings("ignore", message=r"^urllib3 v2 only supports OpenSSL")

环境变量屏蔽警告
bash
```
export PYTHONWARNINGS=ignore
```

根本原因解析

错误根源在于版本不兼容：

urllib3 v2.0 启用了新特性需 OpenSSL 1.1.1+ 支持
macOS 内置 LibreSSL 而非 OpenSSL
Python 默认使用系统 LibreSSL 编译 ssl 模块
三方库如 requests/openai 依赖 urllib3 引发崩溃

开源社区讨论：urllib3 官方声明 v2.0 不再支持旧版 OpenSSL

最佳实践建议

新环境首选：升级 Python 至 3.11+（自带 OpenSSL 1.1.1+）
现有项目：降级 urllib3 至 1.26.x 系列

长期维护：使用虚拟环境隔离依赖

bash

python -m venv .venv
source .venv/bin/activate
pip install urllib3==1.26.6 openai

谨慎操作

直接修改系统级 Python 依赖可能导致其他应用崩溃，建议优先使用虚拟环境

相关文章

urllib3 与 OpenSSL 的兼容性问题 ​

问题描述 ​

解决方案 ​

🔧 方法一：降级 urllib3（推荐） ​

方法二：升级 Python 版本 ​

⚙️ 方法三：手动编译 OpenSSL ​

❌ 不推荐的"解决方案" ​

根本原因解析 ​

最佳实践建议 ​

urllib3 与 OpenSSL 的兼容性问题

问题描述

解决方案

🔧 方法一：降级 urllib3（推荐）

方法二：升级 Python 版本

⚙️ 方法三：手动编译 OpenSSL

❌ 不推荐的"解决方案"

根本原因解析

最佳实践建议