本文旨在解决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免费学习笔记（深入）”；
步骤：
-
安装Homebrew（如果尚未安装）： 打开终端并执行以下命令：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-
通过Homebrew安装Python： 如果您的系统中已经安装了Homebrew Python，可以跳过此步。否则，执行：
brew install python
Homebrew会将Python安装到/usr/local/bin路径下，并自动处理OpenSSL依赖。
-
配置环境变量（确保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
-
验证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的要求相对宽松。
执行步骤：
-
卸载当前urllib3版本：
pip uninstall urllib3
-
安装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为例：
- 打开您的项目。
- 按下Cmd + Shift + P (macOS) 或 Ctrl + Shift + P (Windows/Linux) 打开命令面板。
- 输入Python: Select Interpreter并选择该命令。
- 在弹出的列表中，选择Homebrew安装的Python解释器，其路径通常为/usr/local/bin/python或/usr/local/bin/python3。
以PyCharm为例：
- 打开您的项目。
- 进入 PyCharm -> Preferences (macOS) 或 File -> Settings (Windows/Linux)。
- 导航到 Project: [Your Project Name] -> Python Interpreter。
- 点击齿轮图标，选择 Add Interpreter -> System Interpreter。
- 在路径字段中，手动输入或浏览到 /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配置。
