python/cpython · critical · RuntimeError

stdlib ssl module not available

Error message

stdlib ssl module not available

What it means

Raised in _SSLProtocol.__init__ as RuntimeError when the interpreter's ssl module is None, i.e. this Python build was compiled or installed without working OpenSSL bindings (the stdlib 'import ssl' failed and asyncio.sslproto.ssl is None). It fires as soon as any TLS-over-asyncio connection is attempted on such an interpreter.

Source

Thrown at Lib/asyncio/sslproto.py:276

        # for test only
        self._ssl_protocol._write_backlog.append(data)
        self._ssl_protocol._write_buffer_size += len(data)


class SSLProtocol(protocols.BufferedProtocol):
    max_size = 256 * 1024   # Buffer size passed to read()

    _handshake_start_time = None
    _handshake_timeout_handle = None
    _shutdown_timeout_handle = None

    def __init__(self, loop, app_protocol, sslcontext, waiter,
                 server_side=False, server_hostname=None,
                 call_connection_made=True,
                 ssl_handshake_timeout=None,
                 ssl_shutdown_timeout=None):
        if ssl is None:
            raise RuntimeError("stdlib ssl module not available")

        self._ssl_buffer = bytearray(self.max_size)
        self._ssl_buffer_view = memoryview(self._ssl_buffer)

        if ssl_handshake_timeout is None:
            ssl_handshake_timeout = constants.SSL_HANDSHAKE_TIMEOUT
        elif ssl_handshake_timeout <= 0:
            raise ValueError(
                f"ssl_handshake_timeout should be a positive number, "
                f"got {ssl_handshake_timeout}")
        if ssl_shutdown_timeout is None:
            ssl_shutdown_timeout = constants.SSL_SHUTDOWN_TIMEOUT
        elif ssl_shutdown_timeout <= 0:
            raise ValueError(
                f"ssl_shutdown_timeout should be a positive number, "
                f"got {ssl_shutdown_timeout}")

        if not sslcontext:

View on GitHub (pinned to bc6749cc3b)

Solutions

1. Diagnose the root cause first: run `python -c "import ssl"` — its ImportError shows which shared library or version is missing.
2. Install OpenSSL development packages (e.g. apt install libssl-dev) and rebuild/reinstall Python so the _ssl extension is compiled.
3. Switch to an official Python distribution/docker image known to bundle working SSL (python:* official images, pyenv-built against system libssl).
4. For runtime library issues, fix loader paths (LD_LIBRARY_PATH / conda lib dirs) so _ssl can find libssl.

Example fix

# before: python built without ssl -> RuntimeError on first TLS connection
reader, writer = await asyncio.open_connection('host', 443, ssl=True)

# after: verify at startup and fail fast with a clear message
import ssl
if ssl is None:
    raise SystemExit("this application requires a Python build with SSL support")
reader, writer = await asyncio.open_connection('host', 443, ssl=True)

# startup check, fails fast with a clear message
import sys
try:
    import ssl
except ImportError as e:
    sys.exit(f'Python lacks SSL support ({e}); use a build with OpenSSL')

ssl_ctx = ssl.create_default_context()
reader, writer = await asyncio.open_connection('host', 443, ssl=ssl_ctx)

def ssl_available() -> bool:
    try:
        import ssl  # noqa: F401
        return True
    except ImportError:
        return False

try:
    conn = await loop.create_connection(proto, host, 443, ssl=ctx)
except RuntimeError as e:
    if 'stdlib ssl module not available' in str(e):
        raise SystemExit('reinstall Python with OpenSSL support (libssl-dev + rebuild)')
    raise

When it happens

Trigger: Any asyncio SSL usage — loop.create_connection(..., ssl=ctx), open_connection(ssl=True), create_server(ssl=ctx) — on a Python built without libssl headers or with an incompatible OpenSSL, or in minimal stripped-down runtime images.

Common situations: Custom-compiled CPython on a machine lacking libssl-dev; minimal Docker base images that strip the _ssl extension; macOS/Windows installers with broken SSL paths; exotic platforms (some embedded/AIX) shipping no OpenSSL; Conda/system Python mixes where the _ssl shared object cannot load its OpenSSL.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• Python ssl module is not available
• Socket cannot be of type SSLSocket
• server_hostname is only meaningful with ssl
• You must set server_hostname when using ssl without a host
• ssl_handshake_timeout is only meaningful with ssl

AI-assisted analysis of python/cpython@bc6749cc3b (2026-08-14). Data as JSON: /api/errors/9284debb0dac706d. Report an issue: GitHub.