Python "ModuleNotFoundError: No module named '_ssl'" in CI

The interpreter was built without OpenSSL development headers, so the _ssl extension was skipped. Without it, TLS does not work - and pip itself fails because it cannot make HTTPS connections.

What this error means

Importing ssl fails with ModuleNotFoundError: No module named '_ssl', or pip reports "the ssl module is not available." A from-source interpreter built without OpenSSL headers reproduces this on every TLS attempt.

Python traceback

ModuleNotFoundError: No module named '_ssl'
# or from pip:
WARNING: pip is configured with locations that require TLS/SSL,
however the ssl module in Python is not available.

Common causes

OpenSSL dev headers missing at build time

Building CPython without libssl-dev/openssl-devel skips the _ssl module. The interpreter cannot do TLS and pip cannot reach PyPI.

pyenv build against an OpenSSL it cannot find

On a slim image, a from-source build that does not see OpenSSL headers/libs produces an interpreter with no _ssl.

How to fix it

Install OpenSSL headers and rebuild

Add the dev package, then recompile the interpreter so _ssl is built.

Terminal

# Debian/Ubuntu
apt-get update && apt-get install -y libssl-dev
pyenv install 3.12.4

Or use a prebuilt interpreter with TLS

.github/workflows/ci.yml

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'

How to prevent it

Install libssl-dev (and other CPython build deps) before compiling from source.
Prefer prebuilt interpreters in CI so TLS modules are present.
Verify python -c "import ssl" early in jobs that build interpreters.