Back to blog

How to Fix pip install SSL CERTIFICATE VERIFY FAILED Python Package Errors

When downloading Python libraries using pip install behind a corporate firewall, an active VPN, or a local network proxy, you will occasionally encounter this SSL handshake block:

WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) 
after connection broken by 'SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] 
certificate verify failed: self signed certificate in certificate chain (_ssl.c:1123)'))'

This error blocks package downloads. It means pip rejected the secure HTTPS certificate presented by the Python Package Index (PyPI) repositories because the certificate verification chain is broken.

In this guide, we will analyze why SSL verification breaks on local networks and step through three configuration fixes to bypass or resolve the error.

The Cause: Corporate Decryption and Broken Certificate Chains

When you run pip install, it establishes secure connections to two primary servers: pypi.org (index metadata) and files.pythonhosted.org (source code downloads).

pip validates the security certificates of these servers against your system's Root Certificate Authority (CA) list.

The SSL verification breaks in two scenarios:

  1. Corporate SSL Inspection: Many companies use firewalls that intercept HTTPS traffic to scan for threats. The firewall decrypts your connection, inspects it, and encrypts it again using a self-signed company certificate. Because pip does not trust your company's custom certificate authority, it flags the connection as a potential man-in-the-middle attack and terminates it.
  2. Missing System Certificates: On fresh OS installs (especially macOS), Python may lack root certificates, preventing it from validating modern Let's Encrypt certificates.

Solution 1: Update Root Certificates (macOS Special Fix)

If you are using macOS and recently installed Python, Python does not use the default macOS Keychain certificates natively. Instead, it utilizes its own private cert bundle.

  • The Fix: Run the root certificate update command bundled with your Python installation:
# Navigate to your Python folder and run the command script (adjust Python version as needed)
/Applications/Python\ 3.11/Install\ Certificates.command

This script updates Python's certificate pool, resolving SSL failures for most local systems.

Solution 2: Trust PyPI Servers for a Single Command

If you are executing a one-off install on a secure network proxy, you can tell pip to bypass SSL verification for specific PyPI domains using the --trusted-host flag:

# Force pip to trust the official Python package index hosts
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org pandas
  • Important: Only use this flag for trusted servers (like the official PyPI). Bypassing SSL checks on public unsecured Wi-Fi hotspots exposes your downloads to potential package injections.

Solution 3: Configure pip Configuration Files (Permanent Fix)

Typing --trusted-host on every package installation is tedious. You can save these parameters in pip's global configuration file so they apply to all future commands automatically.

Step 1: Locate or Create the Configuration File

Depending on your operating system, open or create the following file:

  • Windows: %APPDATA%\pip\pip.ini (e.g., C:\Users\Username\AppData\Roaming\pip\pip.ini)
  • Linux / macOS: ~/.config/pip/pip.conf or ~/.pip/pip.conf

Step 2: Inject Trusted Host Parameters

Add the following configuration lines to the file:

[global]
trusted-host = 
    pypi.org
    files.pythonhosted.org

Save the file. You can now execute standard installation commands (e.g., pip install requests) normally without passing flags.

Conclusion

The pip SSL certificate verification failure is caused by local network proxy decryptions or missing root certs. To resolve this block, run Python's built-in certificate installer on macOS, declare PyPI domains using the --trusted-host parameter for individual commands, or write global trusted host configurations to pip.ini or pip.conf files to bypass verification permanently.