Executive Summary & Root Cause Analysis: The error
SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate'))occurs whenpipattempts to download packages over HTTPS from PyPI but cannot validate the server’s TLS certificate chain. Common root causes include: (1) official Python.org installers on macOS missing the bundled root certificate symlinks untilInstall Certificates.commandis run, (2) corporate VPNs, Zscaler, or SSL-inspecting proxies injecting an internal custom Root CA that Python’s bundledcertifistore does not trust, and (3) outdated system CA certificates or an expiredcertifibundle inside older virtual environments or Docker images.
Step 1: Quick Fix – Whitelist PyPI Domains via –trusted-host
To immediately unblock package installation behind a corporate proxy or while testing in a local environment, instruct pip to bypass TLS verification for official PyPI hosts using the --trusted-host flag:
# Pass trusted-host flags for PyPI and its CDN
pip install --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org <package-name>
# First upgrade pip and certifi using the trusted-host flag
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org --upgrade pip certifi
Note: Use --trusted-host only as a temporary workaround or to bootstrap your certificate packages, as it disables TLS certificate verification for those domains.
Step 2: Permanent Environment & Certificate Configuration
Depending on your operating system and network setup, apply the proper permanent root-certificate fix:
- On macOS (Python.org installer): Run the bundled certificate script for your installed Python version:
# Replace 3.12 with your installed Python version /Applications/Python\ 3.12/Install\ Certificates.command - Behind a corporate SSL-inspecting proxy: Export your company’s Root CA certificate in PEM format (e.g.,
corp-ca.pem) and pointpipto it via environment variables orpip.conf/pip.ini:# Linux / macOS: Set environment variable for pip and requests export PIP_CERT=/path/to/corp-ca.pem export REQUESTS_CA_BUNDLE=/path/to/corp-ca.pem # Or persist in ~/.config/pip/pip.conf (Linux/macOS) or %APPDATA%\pip\pip.ini (Windows): [global] cert = /path/to/corp-ca.pem
Step 3: Alternative Workarounds – System Trust Store & OS CA Updates
If your OS trust store already contains the required corporate or public root certificates (common on Windows and managed Linux workstations), configure Python to use the native OS certificate store instead of certifi‘s isolated bundle:
# Install pip-system-certs (use --trusted-host once if currently blocked)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org pip-system-certs
# On Debian/Ubuntu Docker containers, refresh system CA certificates:
sudo apt-get update && sudo apt-get install -y ca-certificates
sudo update-ca-certificates
Verification & Testing Steps
Confirm that pip validates PyPI’s TLS certificate cleanly without needing --trusted-host flags:
# Check which CA bundle Python/pip is currently using
python3 -c "import ssl, certifi; print('certifi:', certifi.where()); print('openssl:', ssl.get_default_verify_paths())"
# Test a standard pip install or search/index check without --trusted-host
pip install --upgrade pip
pip index versions requests
Summary Comparison Table
| Resolution Method | Primary Use Case | Security Level | Persistence |
|---|---|---|---|
--trusted-host CLI flags |
Emergency bootstrap or installing certifi |
Low (Skips TLS verification) | Single command only |
Install Certificates.command |
Fresh macOS Python.org installations | Highest (Validates full TLS chain) | Permanent per Python version |
cert = /path/to/ca.pem in pip.conf |
Corporate VPN / Zscaler / SSL proxies | Highest (Trusts internal Root CA) | Permanent across projects |
pip-system-certs package |
Windows/Linux managed enterprise machines | Highest (Delegates to OS trust store) | Per virtual environment |
Leave a Reply