ERROR pip network_error ai_generated true

ERROR: Could not install packages due to a TLS/SSL error: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self-signed certificate in certificate chain (_ssl.c:1129)

ID: pip/tls-ssl-certificate-verify-failed-self-signed

Also available as: JSON · Markdown · 中文
88%Fix Rate
90%Confidence
1Evidence
2023-08-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
pip 20.3 active — — —
pip 22.0.4 active — — —
pip 23.2 active — — —

Root Cause

The remote server (e.g., a private PyPI mirror or corporate proxy) presents a self-signed SSL certificate that is not trusted by the system's certificate store, causing pip to reject the connection.

generic

中文

远程服务器（例如私有 PyPI 镜像或公司代理）提供了系统证书存储不信任的自签名 SSL 证书，导致 pip 拒绝连接。

Official Documentation

https://pip.pypa.io/en/stable/topics/configuration/#trusted-hosts

Workarounds

  1. 90% success Add the server to trusted hosts: `pip install <package> --trusted-host <hostname>` (e.g., `pip install mypackage --trusted-host pypi.example.com`). This disables SSL verification for that host. 
    Add the server to trusted hosts: `pip install <package> --trusted-host <hostname>` (e.g., `pip install mypackage --trusted-host pypi.example.com`). This disables SSL verification for that host.
  2. 85% success Install the self-signed certificate into the system's trust store: on Linux, copy the .crt file to `/usr/local/share/ca-certificates/` and run `update-ca-certificates`; on macOS, add to Keychain and mark as trusted. 
    Install the self-signed certificate into the system's trust store: on Linux, copy the .crt file to `/usr/local/share/ca-certificates/` and run `update-ca-certificates`; on macOS, add to Keychain and mark as trusted.

中文步骤

  1. 将服务器添加到受信任的主机：`pip install <package> --trusted-host <hostname>`（例如 `pip install mypackage --trusted-host pypi.example.com`）。这将对该主机禁用 SSL 验证。
  2. 将自签名证书安装到系统的信任存储中：在 Linux 上，将 .crt 文件复制到 `/usr/local/share/ca-certificates/` 并运行 `update-ca-certificates`；在 macOS 上，添加到钥匙串并标记为受信任。

Dead Ends

Common approaches that don't work:

  1. 95% fail

    This only changes installation location, not SSL verification; the certificate error persists.

  2. 80% fail

    If the provided certificate is not the exact CA that signed the server certificate, or if the file path is incorrect, pip will still fail with the same error.