Explain Codes LogoExplain Codes Logo

Pip install fails with "connection error:

python
pip
ssl
certificate
Alex KataevbyAlex Kataev·Nov 9, 2024
TLDR

Quickly get past the SSL error by adding --trusted-host flags in your pip install command:

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

This command tells pip to place trust in these hosts when it tries to pull down packages, thereby skipping SSL checks. However, remember, use this sparingly—it's a touch dangerous on the security front!

Digging up the root cause

If you're seeing a CERTIFICATE_VERIFY_FAILED error with pip install, it's essentially pip's way of screaming that it cannot verify the server's SSL certificate. The culprit could be one of many:

  • Out-of-date pip: Older pip just might not vibe with the server’s swanky new certificates.
  • Wonky local cert stores: Your system might be missing the right root certificates, much like a jigsaw puzzle missing pieces.
  • Nosy network interceptors: Firewalls, proxies—they could all rudely interrupt SSL handshakes.

Solving the mystery using pip config

Tweak your pip configuration to get a handle on SSL certificates. Populate your pip.ini (Windows) or .pip/pip.conf (Unix) with the following to set trusted hosts to everyone (just kidding, only the good guys):

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

Just like magic, this tweak applies the fast fix from earlier permanently so you don't have to turn on the terminal gymnastics every time.

Upgrade guide: Pip's younger, cooler sibling

  1. The "Grow Up" upgrade: Execute python -m pip install --upgrade pip to make sure you're hanging out with the coolest version that's in with the latest SSL trends.

  2. The "Fresh Start" reinstall: Call it drastic, but if all else fails, reinstall pip. You could very well get rid of those pesky SSL errors.

Dealing with cert-ifiable issues

Got a custom certificate for your network? Wave it at pip using the --cert option and specify the road to the .pem file:

pip install --cert <path/to/cert>.pem <package-name>

Let's not make things harder than they need to be. For smoother sailing, convert your certificate into the PEM format, so it plays nice with pip.

The notoriously hard-to-deal-with network environment

Working in a corporate environment can be like finding your way through a complicated maze with lots of proxies and special Trusted Root CAs. Time to page in your IT support or network admins for the right certificate deets. Use pip config to tame that wild networking beast.

Keeping an eye on the security

Sure, disabling SSL verification gets the job done, but it's like walking on a razor's edge. You're exposed to scary things, such as Man-in-the-Middle (MitM) attacks. Don't turn a temporary fix into a hard habit.

Backup plans when everything else fails

Hit a brick wall? Try these:

  • easy_install <package-name> might just do the trick.
  • You could also download wheels from PyPI directly and install using pip install <wheel-file>. But remember, no lollygagging on file integrity checks.

Advanced Troubleshooting

If your road remains rocky after following the previous steps:

  • Turn to the logs: Diving into pip.log can unearth detailed SSL error messages.
  • Python & OpenSSL: Ensure you're hanging out with their latest versions as they might be cramping your SSL style.
  • Environment variables: If your certificates choose to reside in non-standard locations, set SSL_CERT_FILE and SSL_CERT_DIR to point the way.