# CondaSSLError：conda 证书报错的原因和正确修法

> CondaSSLError 表示 conda 下载时 HTTPS 证书校验失败，或者 Python 的 ssl 模块加载失败。用 ssl_verify: truststore 或 CA 证书包解决，不要设成 false。

Source: https://ssl.sh/zh/errors/conda-ssl-error/
Last updated: 2026-11-10

**`CondaSSLError: Encountered an SSL error. Most likely a certificate verification issue.` 的意思是：conda 访问频道时 HTTPS 证书校验失败。** 下面打印的 `Exception:` 那一行是具体原因，最常见的是代理重新签名 HTTPS 导致的 `CERTIFICATE_VERIFY_FAILED`。另一种变体 `OpenSSL appears to be unavailable on this machine` 则表示 Python 的 `ssl` 模块加载失败。用 `ssl_verify: truststore` 或 CA 证书包解决信任问题，不要把 `ssl_verify` 设成 false。

## 这条报错是什么意思

CondaSSLError 有两种消息，分别对应证书信任失败和 Python 的 `ssl` 模块加载不了。conda 下载 `repodata.json` 时，requests 库可能抛出 `SSLError`。conda 的 repodata 代码接着会检查能否导入 Python 的 `ssl` 模块，然后以两种消息之一抛出 `CondaSSLError`：

```text
CondaSSLError: Encountered an SSL error. Most likely a certificate verification issue.

Exception: HTTPSConnectionPool(host='repo.anaconda.com', port=443): Max retries exceeded with url: ... (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1006)')))
```

```text
CondaSSLError: OpenSSL appears to be unavailable on this machine. OpenSSL is required to
download and install packages.
```

第一种是信任问题，和 [requests 的 Max retries exceeded](https://ssl.sh/zh/errors/python-requests-max-retries-ssl-error/) 相同；第二种是安装环境有问题，大多出现在 Windows 上。两种情况的修法不同：前者要解决“信任谁”，后者要解决“OpenSSL 能不能加载”，所以先看清楚报的是哪一句。

## 常见原因（按出现频率排序）

CondaSSLError 多数由代理解密 HTTPS 引起，其余 4 种原因按下面的顺序排查。

### 1. 有代理在解密 HTTPS

conda 文档直接点名了这种情况：企业代理会拦截加密流量，干扰 conda 和 pip 的连接，应该把代理的证书配置好，让 requests 能识别它。

- **确认：**

```bash
openssl s_client -connect repo.anaconda.com:443 -servername repo.anaconda.com </dev/null 2>/dev/null | openssl x509 -noout -issuer
```

签发者是公司名称或安全厂商，就可以确认。见[企业 SSL 解密导致的报错](https://ssl.sh/zh/errors/corporate-ssl-inspection/)。

- **修复：** IT 已经把根证书装进 Windows 或 macOS 的，用 `conda config --set ssl_verify truststore`；否则让 `ssl_verify` 指向包含该根证书的 PEM 证书包。

### 2. 没有激活环境就运行 conda（Windows）

conda 排错文档解释过：Windows 通过 `PATH` 查找 DLL，较新的 conda 和 Python 要求先激活环境，让 `Library\bin` 等目录进入 `PATH`。不激活，Python 就加载不了 OpenSSL，于是出现 “OpenSSL appears to be unavailable” 这种变体，或者 `Can't connect to HTTPS URL because the SSL module is not available`。

- **确认：** 在同一个终端里运行 `python -c "import ssl; print(ssl.OPENSSL_VERSION)"`，会失败。
- **修复：** 使用 Anaconda Prompt，或者执行一次 `conda init powershell`（或 `cmd.exe`），然后重新打开终端。

### 3. ssl_verify 指向的文件不存在或不对

`.condarc` 里留着旧路径、文件是 DER 格式而不是 PEM，或者证书包里只有公司根证书、而有些频道并没有被解密。

- **确认：** `conda config --show ssl_verify`，检查文件是否存在、是否以 `-----BEGIN CERTIFICATE-----` 开头。
- **修复：** 用绝对路径指向一个“公开根证书 + 公司根证书”的 PEM 证书包，或者改用 `truststore`。

### 4. 频道或镜像地址本身有证书问题

内网服务器上的自建频道用了私有 CA，或者镜像地址的证书和主机名对不上。Exception 行会出现 `Hostname mismatch` 或者镜像的主机名。

- **修复：** 改正频道地址，或者把内网 CA 加进 `ssl_verify` 的证书包。

### 5. base 环境太老

很老的安装包自带的 CA 证书包可能已经过时，新近启用的公开根证书它不认识，访问某些频道就会失败。用 `truststore` 时会改用系统证书库；否则等网络恢复后，在 base 里更新一次 `ca-certificates` 和 `certifi`。

## 分平台修复命令

各平台的修法都是让 conda 信任正确的根证书：系统证书库里已有就用 `ssl_verify: truststore`，否则让 `ssl_verify` 指向 CA 证书包。

**Windows（IT 已下发公司根证书）：**

```powershell
conda config --set ssl_verify truststore
conda config --show ssl_verify
```

**macOS：**

```bash
conda config --set ssl_verify truststore        # 使用 macOS 系统信任设置
```

**Linux：**

```bash
sudo cp company-root.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates   # Debian/Ubuntu
conda config --set ssl_verify /etc/ssl/certs/ca-certificates.crt
```

**任意系统，只对当前终端（conda 文档介绍的方式）：**

```bash
export REQUESTS_CA_BUNDLE=/path/to/company-bundle.pem
```

**国内镜像：** 下载慢可以按清华镜像站的说明在 `~/.condarc` 里配置镜像，注意地址都是 `https://`：

```yaml
channels:
  - defaults
show_channel_urls: true
default_channels:
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/r
  - https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/msys2
custom_channels:
  conda-forge: https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud
```

改完执行 `conda clean -i` 清除索引缓存。镜像站使用的是正规证书，配置正确时不需要改动 `ssl_verify`；如果换了镜像仍然报 CondaSSLError，问题就在本机或公司网络，而不在镜像。

**多人共用的机器、CI 和镜像：** conda 会从多个位置读取 `.condarc`，包括全系统的配置文件，比如 Linux 上的 `/etc/conda/.condarc`、Windows 上的 `C:/ProgramData/conda/.condarc`。把 `ssl_verify` 写在这里，或者把 `.condarc` 打包进构建镜像，所有用户和每个流水线任务就会使用相同的信任设置。用 `conda config --show-sources` 可以列出每个配置文件以及它设置了哪些值；某个角落里被遗忘的 `ssl_verify: false` 是很常见的意外。

**高校和企业内网：** 不少高校、科研院所和公司的出口有统一的上网认证或安全网关。如果在宿舍或办公室报错、在家里正常，基本可以确定是网络出口在解密 HTTPS 或者需要先认证。先在浏览器里打开任意 HTTPS 网站，看是否跳转到认证页面；再按上面的 `openssl s_client` 命令看证书签发者，向网络管理部门索取根证书，而不是关闭校验。

## 不推荐：关闭证书校验

执行 `conda config --set ssl_verify false` 能让报错消失，代价是下载并执行的软件包失去防篡改保护。conda 文档写明，把 `ssl_verify` 设为 False 会关闭连接的正常安全保护，不推荐这样做；关于禁用 SSL 的页面还警告，这样做意味着通过一条无法确认安全的连接下载并执行任意代码。安装包里的代码会在安装时运行，能篡改连接的人就能替换它们。

更安全的替代办法：用 `ssl_verify: truststore` 复用系统证书库；用 `ssl_verify: /path/bundle.pem` 指定特定 CA；用 `REQUESTS_CA_BUNDLE` 只影响当前终端；Windows 上先激活环境，让 OpenSSL 能正常加载。

## 怎么确认已经修好

修好之后，清掉索引缓存再执行 `conda search` 能正常返回结果：

```bash
conda config --show ssl_verify
conda clean -i
conda search python --info | head -5
```

`conda clean -i` 清掉缓存的索引，让下一条命令重新下载 repodata。搜索应当返回结果，不再出现 `CondaSSLError`。如果你自己托管频道，用 [SSL 检测工具](https://ssl.sh/zh/tools/ssl-checker/)或[证书链补全工具](https://ssl.sh/zh/tools/chain-builder/)检查它的证书链。