CondaSSLError: causes and fixes for conda SSL errors

CondaSSLError: Encountered an SSL error. Most likely a certificate verification issue. means conda's HTTPS request to a channel failed TLS verification. The Exception: line under it holds the real cause, usually CERTIFICATE_VERIFY_FAILED from a proxy that re-signs HTTPS. Fix trust with ssl_verify: truststore or a CA bundle, not ssl_verify: false.

What the error means

CondaSSLError wraps an SSLError from the requests library, and the line under it holds the cause. When conda fetches repodata.json, the requests library may raise SSLError. conda's repodata code then checks whether Python's ssl module can be imported and raises CondaSSLError with one of two messages:

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)')))

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

The first is a trust problem, exactly like requests' Max retries exceeded. The second is a broken installation, most often on Windows.

Causes, most common first

1. A TLS-inspecting proxy

The conda documentation names this case directly: corporate proxies that intercept encrypted traffic interfere with conda and pip, and you should set up the proxy's certificates so the requests package can use them.

• Confirm:

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

An issuer naming your company or a security vendor confirms it. See corporate SSL inspection.

• Fix: conda config --set ssl_verify truststore if IT already installed the root in Windows or macOS, otherwise point ssl_verify at a PEM bundle that contains the root.

2. conda is running without its environment activated (Windows)

conda's troubleshooting guide explains that Windows finds DLLs through PATH, and recent conda and Python builds expect the environment to be activated so that folders like Library\bin are on PATH. Without it, Python cannot load OpenSSL and you get the "OpenSSL appears to be unavailable" variant, or Can't connect to HTTPS URL because the SSL module is not available.

• Confirm: python -c "import ssl; print(ssl.OPENSSL_VERSION)" fails in the same shell.
• Fix: use the Anaconda Prompt, or run conda init powershell (or cmd.exe) once and open a new terminal.

3. ssl_verify points to a missing or wrong file

An old path in .condarc, a DER file instead of PEM, or a bundle that contains only the company root while some channels are not inspected.

• Confirm: conda config --show ssl_verify and check that the file exists and starts with -----BEGIN CERTIFICATE-----.
• Fix: use an absolute path to a PEM bundle that contains public roots plus the company root, or switch to truststore.

4. A channel or mirror URL with certificate problems

A custom channel on an internal server with a private CA, or a mirror URL whose certificate does not match its host name. The Exception line will say Hostname mismatch or name the mirror host.

• Fix: correct the channel URL, or add the internal CA to ssl_verify.

5. Old base environment

An old installer may ship an outdated CA bundle. With truststore the OS store is used instead; otherwise update ca-certificates and certifi in base once connectivity works.

Fix commands by platform

On every platform the fix is to give conda the proxy's root, either through the OS store with ssl_verify: truststore or as a PEM bundle.

Windows (corporate root already deployed by IT):

conda config --set ssl_verify truststore
conda config --show ssl_verify

macOS:

conda config --set ssl_verify truststore        # uses the macOS trust store

Linux:

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

Any OS, per shell (documented by conda):

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

Shared machines, CI runners and images: conda reads configuration from several .condarc locations, including system-wide ones such as /etc/conda/.condarc on Linux and C:/ProgramData/conda/.condarc on Windows. Put ssl_verify there, or bake a .condarc into your build image, so every user and every pipeline job gets the same trust settings. Check what is in effect with conda config --show-sources, which lists each file and the values it sets; a forgotten ssl_verify: false in one of them is a common surprise.

Don't disable certificate verification

Turning off ssl_verify hides the error and lets anyone on the path replace packages. conda config --set ssl_verify false turns the error off. The conda documentation says that setting ssl_verify to False disables the connection's normal security and is not recommended, and its page on disabling SSL warns that downloading without verification means executing arbitrary code fetched over a connection that cannot be verified. Packages contain code that runs on install; anyone who can tamper with the connection can replace them.

The safer alternatives: ssl_verify: truststore to reuse the OS store, ssl_verify: /path/bundle.pem for a specific CA, REQUESTS_CA_BUNDLE for a single shell, and activation on Windows so OpenSSL loads.

Verify the fix

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

conda clean -i clears the cached index so the next command downloads fresh repodata. The search must return results without CondaSSLError. If you host your own channel, check its certificate chain in the SSL checker or chain builder.