解决macOS上Python urllib3与LibreSSL兼容性问题指南

本文旨在解决macos用户在使用python的urllib3库时，因系统自带libressl版本与urllib3 v2+要求openssl 1.1.1+不兼容而导致的`notopensslwarning`错误。教程将指导您通过切换至homebrew安装的python环境、降级urllib3版本以及正确配置ide解释器来有效解决此问题，确保开发环境的稳定运行。

引言：理解macOS上的SSL兼容性挑战

在macOS系统上进行Python开发时，开发者有时会遇到一个常见的兼容性问题：当使用urllib3库进行网络请求时，可能会收到一个NotOpenSSLWarning警告，提示urllib3 v2仅支持OpenSSL 1.1.1+，而当前ssl模块是使用LibreSSL 2.8.3编译的。这通常是由于macOS系统自带的Python环境默认链接到LibreSSL，而现代的urllib3版本对OpenSSL有更严格的要求。虽然系统路径中可能存在LibreSSL相关文件，但这并不意味着Python的ssl模块能够满足urllib3的需求。

本教程将提供一个系统性的解决方案，帮助您解决这一兼容性问题，确保您的Python项目能够顺利运行。

解决方案：切换Python环境与库版本

解决此问题的核心在于绕过macOS系统Python的LibreSSL依赖，并确保Python环境能够使用兼容的OpenSSL版本。以下是推荐的步骤：

1. 切换到Homebrew安装的Python

macOS系统自带的Python版本通常不是最新，且其ssl模块可能链接到LibreSSL。使用Homebrew安装的Python版本通常会链接到Homebrew安装的OpenSSL，从而解决兼容性问题。

立即学习“Python免费学习笔记（深入）”；

步骤：

1. 安装Homebrew（如果尚未安装）： 打开终端并执行以下命令：

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

   登录后复制

2. 通过Homebrew安装Python： 如果您的系统中已经安装了Homebrew Python，可以跳过此步。否则，执行：

   brew install python

   登录后复制

   Homebrew会将Python安装到/usr/local/bin路径下，并自动处理OpenSSL依赖。

3. 配置环境变量（确保Homebrew Python优先）： 为了让系统默认使用Homebrew安装的Python，您需要确保/usr/local/bin路径在您的PATH环境变量中优先于/usr/bin。通常，Homebrew会在安装时提示您添加相应的环境变量配置。如果未自动配置，您可以手动添加到您的shell配置文件（例如~/.zshrc或~/.bashrc）：

   echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc # 如果使用zsh
   # 或
   echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc # 如果使用bash

   登录后复制

   然后，刷新配置文件使更改生效：

   source ~/.zshrc # 或 source ~/.bashrc

   登录后复制

4. 验证Python版本和SSL模块： 执行以下命令确认您正在使用Homebrew安装的Python，并检查其链接的SSL版本：

   which python3
   python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"

   登录后复制

   which python3应该显示/usr/local/bin/python3，而ssl.OPENSSL_VERSION应该显示一个OpenSSL版本（例如OpenSSL 1.1.1t等），而非LibreSSL。

2. 降级urllib3版本（可选但推荐）

如果切换Python环境后问题依然存在，或者作为一种临时的快速解决方案，您可以选择将urllib3库降级到2.0以下的版本。urllib3 v2.0之前的版本对OpenSSL的要求相对宽松。

vizcom.ai

AI草图渲染工具，快速将手绘草图渲染成精美的图像

70

查看详情

执行步骤：

1. 卸载当前urllib3版本：

   pip uninstall urllib3

   登录后复制

2. 安装urllib3的旧版本：

   pip install 'urllib3<2.0'

   登录后复制

   这将安装urllib3的最新1.x版本，例如1.26.18。

3. 配置IDE的Python解释器

如果您使用PyCharm、Visual Studio Code等集成开发环境（IDE），仅仅在终端中切换Python版本是不够的。您还需要在IDE的项目设置中，将Python解释器路径指向Homebrew安装的Python。

以Visual Studio Code为例：

1. 打开您的项目。
2. 按下Cmd + Shift + P (macOS) 或 Ctrl + Shift + P (Windows/Linux) 打开命令面板。
3. 输入Python: Select Interpreter并选择该命令。
4. 在弹出的列表中，选择Homebrew安装的Python解释器，其路径通常为/usr/local/bin/python或/usr/local/bin/python3。

以PyCharm为例：

1. 打开您的项目。
2. 进入 PyCharm -> Preferences (macOS) 或 File -> Settings (Windows/Linux)。
3. 导航到 Project: [Your Project Name] -> Python Interpreter。
4. 点击齿轮图标，选择 Add Interpreter -> System Interpreter。
5. 在路径字段中，手动输入或浏览到 /usr/local/bin/python3 (或 /usr/local/bin/python)，然后点击 OK 应用更改。

注意事项与总结

• 环境隔离： 强烈建议使用Python虚拟环境（venv或conda）来管理项目依赖。即使您切换了全局Python版本，在每个项目中创建虚拟环境可以避免不同项目之间的依赖冲突。在虚拟环境中，您同样需要确保虚拟环境所基于的Python解释器是Homebrew安装的版本。
• PATH的重要性： 确保您的PATH环境变量正确配置，是让系统和IDE识别Homebrew Python的关键。
• 持续更新： 定期使用brew upgrade python更新Homebrew Python，并使用pip install --upgrade pip setuptools更新pip及其依赖，以确保开发环境的最新和安全。

通过以上步骤，您应该能够成功解决macOS上urllib3与LibreSSL的兼容性问题，避免NotOpenSSLWarning，从而确保您的Python网络请求功能正常运行。核心思想是利用Homebrew提供的更现代且兼容性更好的Python和OpenSSL环境，并根据需要调整库版本和IDE配置。

以上就是解决macOS上Python urllib3与LibreSSL兼容性问题指南的详细内容，更多请关注php中文网其它相关文章！