ERROR pip network_error ai_generated partial

pip._vendor.urllib3.exceptions.SSLError: [SSL: SSL3_ALERT_HANDSHAKE_FAILURE] sslv3 alert handshake failure (_ssl.c:1129)

ID: pip/ssl-sslv3-alert-handshake-failure

Also available as: JSON · Markdown · 中文
70%Fix Rate
85%Confidence
1Evidence
2024-01-12First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
pip 23.2 active — — —
pip 24.0 active — — —
Python 3.9 active — — —
Python 3.10 active — — —
Python 3.11 active — — —
Python 3.12 active — — —
OpenSSL 1.1.1 active — — —
OpenSSL 3.0 active — — —

Root Cause

The server's TLS configuration is incompatible with the client's SSL/TLS settings, often due to the server requiring a cipher or protocol version that the client's OpenSSL library does not support, or vice versa.

generic

中文

服务器的 TLS 配置与客户端的 SSL/TLS 设置不兼容，通常是因为服务器要求客户端 OpenSSL 库不支持的密码或协议版本，反之亦然。

Official Documentation

https://pip.pypa.io/en/stable/topics/https-certificates/

Workarounds

  1. 80% success Upgrade Python to a version that includes a newer OpenSSL (e.g., Python 3.12+ often uses OpenSSL 3.0) or recompile Python with a modern OpenSSL: install Python 3.12 from python.org and retry. 
    Upgrade Python to a version that includes a newer OpenSSL (e.g., Python 3.12+ often uses OpenSSL 3.0) or recompile Python with a modern OpenSSL: install Python 3.12 from python.org and retry.
  2. 60% success If the server is internal or known, configure pip to use a different TLS version by setting the environment variable: SSL_CERT_FILE=/path/to/custom/cert.pem and also try: export OPENSSL_CONF=/dev/null (to reset OpenSSL config) or use a proxy that handles TLS. 
    If the server is internal or known, configure pip to use a different TLS version by setting the environment variable: SSL_CERT_FILE=/path/to/custom/cert.pem and also try: export OPENSSL_CONF=/dev/null (to reset OpenSSL config) or use a proxy that handles TLS.
  3. 70% success Use a different package index that supports older TLS versions, or mirror the packages to a compatible server: pip install --index-url https://mirror.example.com/simple package 
    Use a different package index that supports older TLS versions, or mirror the packages to a compatible server: pip install --index-url https://mirror.example.com/simple package

中文步骤

  1. 将 Python 升级到包含较新 OpenSSL 的版本（例如，Python 3.12+ 通常使用 OpenSSL 3.0）或使用现代 OpenSSL 重新编译 Python：从 python.org 安装 Python 3.12 并重试。
  2. 如果服务器是内部或已知的，通过设置环境变量配置 pip 使用不同的 TLS 版本：SSL_CERT_FILE=/path/to/custom/cert.pem，并尝试：export OPENSSL_CONF=/dev/null（重置 OpenSSL 配置）或使用处理 TLS 的代理。
  3. 使用支持较旧 TLS 版本的其他软件包索引，或将软件包镜像到兼容的服务器：pip install --index-url https://mirror.example.com/simple package

Dead Ends

Common approaches that don't work:

  1. Setting PIP_CERT or REQUESTS_CA_BUNDLE to a custom CA bundle 95% fail

    The error is a handshake failure, not a certificate verification failure; changing CA bundles does not affect the TLS handshake protocol negotiation.

  2. Using pip install --trusted-host pypi.org to bypass SSL 90% fail

    This only disables certificate verification, not the TLS handshake; the handshake failure still occurs.

  3. Upgrading pip alone without upgrading Python's SSL module 85% fail

    The SSL module is part of Python's standard library and is not updated by pip; upgrading pip does not change the underlying OpenSSL library.