[Fixed] SSL: CERTIFICATE_VERIFY_FAILED in pip: Step-by-Step Troubleshooting Guide

Executive Summary & Root Cause Analysis: The error SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate')) occurs when pip attempts 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 until Install Certificates.command is run, (2) corporate VPNs, Zscaler, or SSL-inspecting proxies injecting an internal custom Root CA that Python’s bundled certifi store does not trust, and (3) outdated system CA certificates or an expired certifi bundle 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:

  1. 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
  2. Behind a corporate SSL-inspecting proxy: Export your company’s Root CA certificate in PEM format (e.g., corp-ca.pem) and point pip to it via environment variables or pip.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