{
  "id": "pip/ssl-sslv3-alert-handshake-failure",
  "signature": "pip._vendor.urllib3.exceptions.SSLError: [SSL: SSL3_ALERT_HANDSHAKE_FAILURE] sslv3 alert handshake failure (_ssl.c:1129)",
  "signature_zh": "pip._vendor.urllib3.exceptions.SSLError：[SSL: SSL3_ALERT_HANDSHAKE_FAILURE] sslv3 警报握手失败 (_ssl.c:1129)",
  "regex": "SSL: SSL3_ALERT_HANDSHAKE_FAILURE",
  "domain": "pip",
  "category": "network_error",
  "subcategory": null,
  "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.",
  "root_cause_type": "generic",
  "root_cause_zh": "服务器的 TLS 配置与客户端的 SSL/TLS 设置不兼容，通常是因为服务器要求客户端 OpenSSL 库不支持的密码或协议版本，反之亦然。",
  "versions": [
    {
      "version": "pip 23.2",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "pip 24.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python 3.9",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python 3.10",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python 3.11",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Python 3.12",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "OpenSSL 1.1.1",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "OpenSSL 3.0",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Setting PIP_CERT or REQUESTS_CA_BUNDLE to a custom CA bundle",
      "why_fails": "The error is a handshake failure, not a certificate verification failure; changing CA bundles does not affect the TLS handshake protocol negotiation.",
      "fail_rate": 0.95,
      "condition": "",
      "sources": []
    },
    {
      "action": "Using pip install --trusted-host pypi.org to bypass SSL",
      "why_fails": "This only disables certificate verification, not the TLS handshake; the handshake failure still occurs.",
      "fail_rate": 0.9,
      "condition": "",
      "sources": []
    },
    {
      "action": "Upgrading pip alone without upgrading Python's SSL module",
      "why_fails": "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.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "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.",
      "success_rate": 0.8,
      "how": "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.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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.",
      "success_rate": 0.6,
      "how": "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.",
      "condition": "",
      "sources": []
    },
    {
      "action": "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",
      "success_rate": 0.7,
      "how": "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",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "将 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"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://pip.pypa.io/en/stable/topics/https-certificates/",
  "official_doc_section": null,
  "error_code": "ERROR",
  "verification_tier": "ai_generated",
  "confidence": 0.85,
  "fix_success_rate": 0.7,
  "resolvable": "partial",
  "first_seen": "2024-01-12",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}