pip._vendor.urllib3.exceptions.SSLError：[SSL: SSL3_ALERT_HANDSHAKE_FAILURE] sslv3 警报握手失败 (_ssl.c:1129)
pip._vendor.urllib3.exceptions.SSLError: [SSL: SSL3_ALERT_HANDSHAKE_FAILURE] sslv3 alert handshake failure (_ssl.c:1129)
ID: pip/ssl-sslv3-alert-handshake-failure
版本兼容性
| 版本 | 状态 | 引入 | 弃用 | 备注 |
|---|---|---|---|---|
| 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 | — | — | — |
根因分析
服务器的 TLS 配置与客户端的 SSL/TLS 设置不兼容，通常是因为服务器要求客户端 OpenSSL 库不支持的密码或协议版本，反之亦然。
English
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.
官方文档
https://pip.pypa.io/en/stable/topics/https-certificates/解决方案
-
将 Python 升级到包含较新 OpenSSL 的版本（例如，Python 3.12+ 通常使用 OpenSSL 3.0）或使用现代 OpenSSL 重新编译 Python：从 python.org 安装 Python 3.12 并重试。
-
如果服务器是内部或已知的，通过设置环境变量配置 pip 使用不同的 TLS 版本：SSL_CERT_FILE=/path/to/custom/cert.pem，并尝试：export OPENSSL_CONF=/dev/null（重置 OpenSSL 配置）或使用处理 TLS 的代理。
-
使用支持较旧 TLS 版本的其他软件包索引，或将软件包镜像到兼容的服务器：pip install --index-url https://mirror.example.com/simple package
无效尝试
常见但无效的做法:
-
Setting PIP_CERT or REQUESTS_CA_BUNDLE to a custom CA bundle
95% 失败
The error is a handshake failure, not a certificate verification failure; changing CA bundles does not affect the TLS handshake protocol negotiation.
-
Using pip install --trusted-host pypi.org to bypass SSL
90% 失败
This only disables certificate verification, not the TLS handshake; the handshake failure still occurs.
-
Upgrading pip alone without upgrading Python's SSL module
85% 失败
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.