Fixing pip SSL Certificate Errors on Corporate Networks

by

Overview

When working in a corporate environment, developers often run into unexpected issues due to network security configurations. One such common problem is the SSL certificate verification error when installing Python packages using pip.

Below is an example of the error message:

PowerShell
python -m pip install django~=4.2.0                                               

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: unable to get local issuer certificate (_ssl.c:1006)'))': /simple/django/
WARNING: Retrying (Retry(total=3, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006)'))': /simple/django/
...

This error usually has nothing to do with Python or pip itself, but rather with the company’s network setup.

Why This Happens

Most corporate networks use internal proxies or firewalls to monitor and control internet traffic. For security reasons, these systems often perform SSL interception, replacing external certificates with their own internal root certificates. While this works fine for browsers that have the internal certificates installed, pip and other command-line tools do not recognize these certificates by default.

As a result, pip is unable to verify the SSL certificate of the external repository (such as pypi.org), and fails with a certificate verification error.

Quick Fix: Use trusted-host

You can instruct pip to skip certificate verification for specific domains by marking them as trusted hosts.

Run the following command to update your global pip configuration:

PowerShell
pip config set global.trusted-host "pypi.org files.pythonhosted.org pypi.python.org"

Alternatively, when installing a package, you can use the --trusted-host option inline:

PowerShell
pip install <package-name> --trusted-host pypi.org --trusted-host files.pythonhosted.org --trusted-host pypi.python.org

This tells pip to bypass SSL verification for these hosts, which resolves the issue in most cases.

Permanent Fix via Configuration File

Instead of typing trusted-hosts every time, you can edit your pip configuration file directly.

👍 For Windows:

PowerShell
pip config set global.trusted-host "pypi.org files.pythonhosted.org pypi.python.org" --trusted-host=pypi.python.org --trusted-host=pypi.org --trusted-host=pythonhosted.org

Writing to C:\Users\wizpread\AppData\Roaming\pip\pip.ini

For macOS/Linux:

PowerShell
~/.pip/pip.conf

Add the following content:

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

This ensures that all future pip commands automatically trust these hosts.

Security Considerations

While this fix works, it comes with security trade-offs. Disabling SSL certificate verification exposes your machine to potential man-in-the-middle (MITM) attacks. If your company provides a custom root certificate, a more secure solution is to install that certificate system-wide and let pip use it for verification.

Another long-term solution is to set up an internal PyPI mirror that operates within your company’s network and uses the trusted internal certificates.

Conclusion

SSL certificate verification errors with pip are a common issue in corporate environments with strict network controls. The trusted-host workaround provides a quick and effective fix, but be aware of the security implications. If you’re facing this problem, consider discussing a more permanent and secure approach with your IT or DevOps team.

If you’ve encountered this error, try the solution above—it might save you hours of troubleshooting.

Leave a Comment