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

- **ID:** `pip/ssl-sslv3-alert-handshake-failure`
- **Domain:** pip
- **Category:** network_error
- **Error Code:** `ERROR`
- **Verification:** ai_generated
- **Fix Rate:** 70%

## 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.

## Version Compatibility

| Version | Status | Introduced | Deprecated |
|---------|--------|------------|------------|
| 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 | — | — |

## Workarounds

1. **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.** (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.
   ```
2. **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.** (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.
   ```
3. **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** (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
   ```

## Dead Ends

- **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% fail)
- **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% fail)
- **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% fail)