macOS环境下解决Python urllib3与LibreSSL的兼容性问题

针对macos用户在使用python及urllib3时，因系统默认的libressl版本与urllib3 v2+要求的openssl 1.1.1+不兼容而导致的`notopensslwarning`，本文提供了一套综合解决方案。核心策略包括切换至homebrew安装的python环境、必要时降级urllib3版本，以及正确配置ide的python解释器路径，确保python的ssl模块能满足现代库的需求。

引言：理解NotOpenSSLWarning

在使用Python进行网络请求，特别是依赖urllib3库时，macOS用户可能会遇到一个常见的警告信息：NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL X.X.X'. 这个警告表明，当前Python环境的ssl模块所编译链接的SSL库（通常是macOS系统自带的LibreSSL）版本不符合urllib3版本2及更高版本所要求的OpenSSL 1.1.1+标准。尽管这通常是一个警告而非错误，但它可能导致某些功能受限或潜在的安全风险，并且在某些情况下可能阻碍应用程序的正常运行。

问题根源分析

macOS系统自带的Python（通常位于/usr/bin/python）往往被编译为使用LibreSSL，这是Apple在其操作系统中采用的SSL/TLS库。然而，许多现代的Python库，如urllib3的最新版本，已经明确要求底层ssl模块必须与OpenSSL 1.1.1或更高版本兼容。当Python解释器链接到LibreSSL时，即使系统中安装了最新版本的LibreSSL，其API和功能可能仍无法完全满足urllib3对OpenSSL的严格要求，从而触发上述警告。简单地将LibreSSL的路径添加到PATH环境变量中，并不能改变Python解释器本身在编译时链接的SSL库。

解决方案一：采用Homebrew管理Python环境（推荐）

最推荐且最彻底的解决方案是使用Homebrew在macOS上安装和管理Python。Homebrew安装的Python通常会正确地链接到OpenSSL，从而避免与LibreSSL相关的兼容性问题。

1. 安装或确保使用Homebrew Python

如果您尚未安装Homebrew，请访问其官方网站进行安装。安装Homebrew后，可以通过以下命令安装Python：

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

brew install python

如果已经安装，Homebrew会提示已安装。此时，请确保您的系统使用的是Homebrew安装的Python版本。Homebrew安装的Python通常位于/usr/local/bin/python3或/usr/local/bin/python。

2. 配置Shell环境

为了确保系统默认使用Homebrew安装的Python，您需要调整Shell的PATH环境变量，使其优先指向Homebrew的二进制目录。

对于Bash用户，编辑~/.bash_profile或~/.bashrc：

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bash_profile # 或 ~/.bashrc
source ~/.bash_profile # 或 source ~/.bashrc

对于Zsh用户，编辑~/.zshrc：

听脑AI

听脑AI语音，一款专注于音视频内容的工作学习助手，为用户提供便捷的音视频内容记录、整理与分析功能。

745

查看详情

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

配置完成后，请关闭并重新打开终端，或执行source命令使配置生效。

3. 验证Python及其SSL模块

通过以下命令验证当前使用的Python版本及其链接的SSL库：

which python3 # 确认路径是否为 /usr/local/bin/python3
python3 --version # 确认版本
python3 -c "import ssl; print(ssl.OPENSSL_VERSION)" # 确认SSL版本是否为OpenSSL 1.1.1+

如果ssl.OPENSSL_VERSION显示为OpenSSL 1.1.1或更高版本，则表示Python环境已正确配置。

解决方案二：降级urllib3版本（临时方案）

如果暂时无法切换Python环境，或者需要快速解决问题，可以考虑将urllib3降级到其版本2之前的版本。这些旧版本对SSL库的要求不那么严格，因此可以与LibreSSL兼容。

pip uninstall urllib3
pip install 'urllib3<2.0'

注意事项：

• 这是一个临时性的解决方案，不推荐作为长期策略。
• 降级库版本可能导致无法使用urllib3最新版本提供的新功能、性能改进或安全修复。
• 在未来，您可能仍然需要升级Python环境以支持最新的urllib3版本。

解决方案三：配置集成开发环境（IDE）

如果您在使用PyCharm、Visual Studio Code等IDE进行开发，仅仅在终端中配置Python环境是不够的。您还需要在IDE中明确指定使用Homebrew安装的Python解释器。

1. Visual Studio Code

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

2. PyCharm

1. 打开PyCharm，进入您的项目。
2. 导航到PyCharm -> Preferences (macOS) 或 File -> Settings (Windows/Linux)。
3. 在左侧面板中，展开Project: [Your Project Name]，然后选择Python Interpreter。
4. 点击齿轮图标，选择Add Interpreter。
5. 选择System Interpreter，然后在Interpreter路径中，手动指定Homebrew安装的Python路径，例如/usr/local/bin/python3。
6. 点击OK保存设置。

总结与最佳实践

解决macOS上Python与LibreSSL兼容性问题的关键在于确保Python解释器链接到符合现代标准的OpenSSL库。通过Homebrew管理Python环境是最佳实践，它能提供一个独立、易于管理且通常链接到OpenSSL的Python版本。当遇到NotOpenSSLWarning时，首先应检查并配置Python环境，确保其SSL后端满足要求。降级urllib3版本可以作为临时措施，但长期来看，升级Python环境是更稳妥的选择。同时，不要忘记在您使用的任何IDE中同步更新Python解释器路径，以确保开发环境的一致性。

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