Improve error message for SSL: CERTIFICATE_VERIFY_FAILED error

Ideas
1

I propose to clarify the SSL: CERTIFICATE_VERIFY_FAILED error message on macOS to encourage users to install the appropriate certificates rather than just deactivating SSL verification.

The Python installer for macOS does not automatically install the SSL root certificates, and many users don’t notice the message recommending that they run Install Certificates.command. As a result, the SSL: CERTIFICATE_VERIFY_FAILED error is very common.

Sadly, a very popular “solution” found online (here or there, for example) is to simply deactivate SSL verification, typically by running:

import ssl
ssl._create_default_https_context = ssl._create_unverified_context

or by setting the PYTHONHTTPSVERIFY environment variable to 0.

This is obviously a terrible idea from a security perspective!

I don’t know how many people use SSL without SSL verification, and how many unsafe projects are in production, but judging by how frequently this issue pops up in my repos and in many others, I’d guess quite a lot.

One option would be to make sure that the Python installer installs SSL certificates unless the user opts out. That might be my preferred solution.

But until this happens, we could at the very least improve the error message to encourage the user to install SSL root certificates (e.g., by using pip install certifi), and to strongly recommend not deactivating SSL verification.

What do you think?

3 Likes
2

I agree with every one of your points. The current giant traceback is an unacceptably bad user experience. Requiring a separate opt-in certification installation is also a bad user experience.

4 Likes
3

On Windows the error message can be very unhelpful also.

The >3k views on "SSL: CERTIFICATE_VERIFY_FAILED" error on Python 3.9.6 (Windows 10) probably include many people searching for some solution.

(As mentioned in SSL certificate debugging the message is sometimes very misleading.)

pip install certifi is likely a completely wrong direction on Windows though, so this would maybe have to be a platform specific message.

2 Likes