# pip._vendor.urllib3.exceptions.SSLError：[SSL: SSL3_ALERT_HANDSHAKE_FAILURE] sslv3 警报握手失败 (_ssl.c:1129)

- **ID:** `pip/ssl-sslv3-alert-handshake-failure`
- **领域:** pip
- **类别:** network_error
- **错误码:** `ERROR`
- **验证级别:** ai_generated
- **修复率:** 70%

## 根因

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

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| 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 | — | — |

## 解决方案

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
   ```

## 无效尝试

- **Setting PIP_CERT or REQUESTS_CA_BUNDLE to a custom CA bundle** — The error is a handshake failure, not a certificate verification failure; changing CA bundles does not affect the TLS handshake protocol negotiation. (95% 失败率)
- **Using pip install --trusted-host pypi.org to bypass SSL** — This only disables certificate verification, not the TLS handshake; the handshake failure still occurs. (90% 失败率)
- **Upgrading pip alone without upgrading Python's SSL module** — 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. (85% 失败率)