Fix urllib3 OpenSSL Compatibility Error on macOS

Encountering the ImportError: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with LibreSSL 2.8.3 error typically occurs when newer Python packages encounter incompatible SSL libraries, especially on macOS systems with older LibreSSL versions. Below are solutions to resolve this issue.

---

Why This Happens

Starting from urllib3 v2.0, OpenSSL 1.1.1+ is required for security and compatibility features. macOS often ships with LibreSSL (instead of OpenSSL), leading to conflicts. Common triggers:

• Python environments linked to system LibreSSL.
• Packages like openai installing urllib3 v2.0+ automatically.

---

✅ Recommended Solutions

Solution 1: Downgrade urllib3 (Quick Fix)

Downgrade urllib3 to a compatible version that supports LibreSSL:

pip uninstall urllib3  
pip install 'urllib3<2.0'  
# Or specify an exact working version  
pip install urllib3==1.26.6

Why it works: Releases older than v2.0 don’t require OpenSSL 1.1.1+ and work with LibreSSL.

Solution 2: Install Python 3.11+

Upgrade Python to a version with modern SSL support (via Homebrew):

brew install python@3.12  # Installs updated OpenSSL-linked Python  
python3.12 -m venv venv  # Recreate a virtual environment  
source venv/bin/activate  
pip install -r requirements.txt  # Reinstall packages

Why it works: Newer Python versions (≥3.11) ship with OpenSSL ≥1.1.1, resolving the dependency conflict.

Solution 3: Use Official Python Installer

Install Python directly from python.org, which includes OpenSSL:

1. Download and install the macOS package.
2. Run the included shell updater:

/Applications/Python\ 3.x/Update\ Shell\ Profile.command

3. Use the path /usr/local/bin/python3 post-install.

---

Advanced: Build Python with OpenSSL

Force Python to compile against OpenSSL (skip if Solutions 1-3 work):

# Build OpenSSL 1.1.1d  
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=/usr/local/openssl --openssldir=/usr/local/openssl  
make -j$(sysctl -n hw.logicalcpu)  
make install  

# Reinstall Python using the new OpenSSL  
PYTHON_CONFIGURE_OPTS="--with-openssl=/usr/local/openssl" pyenv install 3.9.6

Verify:

import ssl  
print(ssl.OPENSSL_VERSION_INFO)  # Should show (1, 1, 1, ...)

---

❌ Not Recommended

Avoid these approaches unless unavoidable:

• Suppressing warnings:

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

Risk: Masks underlying security issues.

• Environment-level ignoring:

export PYTHONWARNINGS=ignore  # Added to .zshrc/.bashrc

Risk: Hides all Python warnings, including unrelated security alerts.

---

Best Practices

1. Prioritize OpenSSL upgrades: Future-proof environments using Python ≥3.11 or compiling with OpenSSL.
2. Test after fixes: Run import openai or import urllib3 to confirm resolution.
3. Use virtual environments: Prevent clobbering system dependencies.

These solutions address incompatibility at the SSL-library level while ensuring secure, maintainable environments.

Caution

Downgrading urllib3 exposes your environment to unpatched vulnerabilities in older versions. Only use this as a temporary fix if upgrading Python/OpenSSL isn’t feasible.