本文旨在解决macOS用户在使用Python的urllib3库时，因系统自带LibreSSL版本与urllib3 v2要求OpenSSL 1.1.1+不兼容而导致的`NotOpenSSLWarning`错误。教程将提供三种主要解决方案：切换至Homebrew安装的Python版本、降级urllib3库，以及配置IDE使用正确的Python解释器，确保开发环境的稳定运行。
macOS上Python urllib3与LibreSSL兼容性问题解析与解决方案
在macOS系统上进行Python开发时，开发者可能会遇到一个常见的兼容性问题，尤其是在使用urllib3库版本2.0及以上时。当系统默认的Python ssl模块是基于较旧的LibreSSL版本（例如LibreSSL 2.8.3）编译时，而urllib3 v2则明确要求OpenSSL 1.1.1+，这会导致Python环境抛出NotOpenSSLWarning警告。此警告通常伴随着像Selenium这类依赖HTTP请求的库无法正常工作，因为底层SSL连接未能正确建立。
问题的核心在于macOS系统自带的Python环境及其SSL库的配置。即使通过Homebrew安装了LibreSSL并尝试将其路径导出到PATH环境变量，系统默认的Python解释器可能仍然使用其内置或预编译的SSL模块，而非Homebrew安装的版本。
本教程将详细介绍如何诊断并解决这一问题，确保您的Python开发环境能够稳定运行。
立即学习“Python免费学习笔记（深入）”；
1. 理解问题根源
urllib3是一个强大的HTTP客户端库，广泛用于Python应用程序中。从urllib3版本2.0开始，它引入了对OpenSSL 1.1.1或更高版本的严格依赖，以利用其提供的安全特性和性能优化。然而，macOS系统自带的Python通常会链接到Apple提供的LibreSSL库，其版本可能低于urllib3 v2的要求。当两者不匹配时，便会触发警告。
错误信息通常如下所示：
NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL 2.8.3'. See: https://github.com/urllib3/urllib3/issues/3020
2. 解决方案一：切换到Homebrew安装的Python版本
解决此问题的最推荐方法是使用通过Homebrew安装的Python版本，而不是macOS系统自带的Python。Homebrew安装的Python通常会正确地链接到兼容的OpenSSL版本，或者至少提供一个更易于管理的Python环境。
步骤：
-
安装Homebrew（如果尚未安装） 打开终端并执行以下命令：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-
通过Homebrew安装Python 如果您已经安装了Python，Homebrew会提示您已安装。如果没有，它将安装最新稳定版。
brew install python
Homebrew通常会将Python安装到/usr/local/bin/python3或/opt/homebrew/bin/python3（对于Apple Silicon Mac）。它还会自动将这些路径添加到您的PATH环境变量中。
-
验证Python版本和路径 安装完成后，请验证您的终端现在使用的是Homebrew安装的Python：
which python3 python3 --version
确认which python3的输出路径是Homebrew安装路径（例如/usr/local/bin/python3），而不是/usr/bin/python3。
-
重新安装或更新项目依赖 切换到Homebrew Python后，建议在您的项目环境中重新安装所有依赖，以确保它们链接到新的Python解释器及其SSL模块。
# 确保使用Homebrew Python的pip /usr/local/bin/python3 -m pip install --upgrade pip /usr/local/bin/python3 -m pip install -r requirements.txt # 如果有requirements.txt # 或者单独安装urllib3 /usr/local/bin/python3 -m pip install urllib3
3. 解决方案二：降级urllib3库
如果切换Python版本不方便，或者在某些特定情况下问题仍然存在，您可以选择将urllib3库降级到版本2.0以下。这是一个临时的解决方案，因为它限制了您使用urllib3的最新功能和安全更新，但可以立即解决兼容性警告。
步骤：
-
卸载当前版本的urllib3
pip uninstall urllib3
如果您的系统中有多个Python环境，请确保使用与您项目相关的pip命令。例如，如果您的项目使用的是Homebrew Python，则使用/usr/local/bin/python3 -m pip uninstall urllib3。
-
安装特定版本的urllib3 安装任何低于2.0版本的urllib3，例如1.26.x系列。
pip install 'urllib3<2.0'
同样，请确保使用正确的pip命令。
4. 解决方案三：配置IDE使用正确的Python解释器
对于使用集成开发环境（IDE）如PyCharm、Visual Studio Code或其他编辑器的开发者来说，即使您在终端中切换了Python版本，IDE可能仍然配置为使用系统默认的Python解释器。这是导致问题持续存在的一个常见原因。
步骤：
识别Homebrew Python解释器路径 通常，Homebrew安装的Python解释器路径为/usr/local/bin/python3（对于Intel Mac）或/opt/homebrew/bin/python3（对于Apple Silicon Mac）。
-
在IDE中更改Python解释器路径
-
PyCharm:
- 打开您的项目。
- 进入 PyCharm -> Preferences (或 File -> Settings on Windows/Linux)。
- 导航到 Project: [Your Project Name] -> Python Interpreter。
- 点击齿轮图标，选择 Add Interpreter -> Add Local Interpreter。
- 选择 System Interpreter 或 Virtualenv Environment，然后手动指定Homebrew Python的路径（例如/usr/local/bin/python3）。
- 应用更改。
-
Visual Studio Code:
- 打开您的项目。
- 按下 Cmd+Shift+P (macOS) 或 Ctrl+Shift+P (Windows/Linux) 打开命令面板。
- 输入 Python: Select Interpreter 并选择该命令。
- 选择Homebrew Python的路径（它通常会出现在列表中，如果没有，选择 Enter interpreter path... 并手动输入）。
-
注意事项与最佳实践
- 虚拟环境（Virtual Environments）： 强烈建议为每个Python项目使用独立的虚拟环境（如venv或conda）。这有助于隔离项目依赖，避免不同项目之间的版本冲突，并确保您的项目始终使用正确的Python解释器和库版本。
- PATH环境变量： 尽管Homebrew会自动管理PATH，但如果您遇到which python3仍然指向系统Python的问题，可能需要手动检查并修改您的shell配置文件（如~/.bashrc, ~/.zshrc）。确保export PATH="/usr/local/bin:$PATH"或export PATH="/opt/homebrew/bin:$PATH"在其他可能覆盖它的路径之前。
- 定期更新： 定期使用brew update和brew upgrade python来更新Homebrew和Python，确保您使用的是最新且安全的版本。
- 理解系统Python与Homebrew Python： 明确区分macOS自带的Python和通过Homebrew安装的Python。通常，系统Python用于操作系统内部功能，不建议直接修改或依赖它进行开发。
总结
解决macOS上urllib3与LibreSSL的兼容性问题主要围绕着确保您的Python环境使用一个与urllib3 v2兼容的SSL库。最稳健的长期解决方案是切换到Homebrew安装的Python版本，并相应地配置您的IDE。作为临时或辅助方案，降级urllib3库也可以快速解决警告。通过遵循本教程的步骤，您可以有效地管理Python环境，避免SSL相关的兼容性问题，从而专注于您的开发工作。
