OpenAI Just Swapped Its HTTP Library. Your Docker Builds Might Break.

Q: What Actually Changed

Previous versions of the OpenAI Python SDK pulled in httpx and certifi as transitive dependencies. certifi bundles Mozilla's CA certificate store as a Python package — it's the default trust store for virtually every Python HTTP client that isn't exp

Q: Where This Breaks

The shift from certifi to OS trust store is a design improvement for most systems — you get your distro's CA updates, you don't carry a redundant 300KB bundle, and you don't have certifi version skew. But two deployment patterns catch the sharp edge:

OpenAI pushed Python SDK v3.5.0 and quietly swapped httpx for HTTPX2 under the hood. The migration is mostly transparent — unless you're deploying in a Docker container without system CA certificates. In that case, your API calls are about to throw ssl.SSLCertVerificationError and you won't immediately know why.

I installed it, checked the dependency tree, and ran down what actually changed. Here's the breakdown.

What Actually Changed

Previous versions of the OpenAI Python SDK pulled in httpx and certifi as transitive dependencies. certifi bundles Mozilla's CA certificate store as a Python package — it's the default trust store for virtually every Python HTTP client that isn't explicitly configured otherwise.

OpenAI SDK v3.5.0 ships with none of that:

$ pip install openai
# Installs: openai, httpx2, httpcore2, truststore, pydantic, ...
# Does NOT install: httpx, certifi

I verified this in a clean environment:

import httpx2
print(httpx2.__version__)  # 2.12.0

import httpx   # ImportError — not installed
import certifi # ImportError — not installed

import truststore
print(truststore.__version__)  # 0.10.4

Three things happened in one release:

httpx → httpx2: A Pydantic-led continuation of the httpx project (which saw limited maintenance activity). API surface is identical — Client, AsyncClient, Response, Timeout, all there with the same signatures.
certifi → truststore: The default TLS trust store is now the operating system's certificate store, accessed via the truststore package. On Linux, that means reading from /etc/ssl/certs/ instead of a bundled Mozilla bundle.
Default client auto-migrates: Constructing OpenAI(timeout=30.0) without a custom http_client silently picks up DefaultHttpx2Client with OS trust store.

Where This Breaks

The shift from certifi to OS trust store is a design improvement for most systems — you get your distro's CA updates, you don't carry a redundant 300KB bundle, and you don't have certifi version skew. But two deployment patterns catch the sharp edge:

1. Minimal Docker images

Alpine-based images (python:3.13-alpine), distroless images (gcr.io/distroless/python3-debian12), and many slimmed-down production containers don't ship a full CA certificate store. They're designed to let the application bundle or mount its own certs. When truststore tries to open /etc/ssl/certs/ca-certificates.crt and finds nothing, every HTTPS request to api.openai.com fails.

2. Corporate TLS inspection proxies

Enterprise environments that intercept TLS with a corporate CA won't break — they'll behave differently. Previously you'd drop your internal CA into a custom certifi bundle or monkey-patch the trust store. Now you need to point at the OS trust store, which may or may not have the corporate CA installed depending on how the container is built.

The Fix

OpenAI's migration guide documents the workaround, but it's a single note at the bottom of a migration doc — easy to miss if you're not reading changelogs:

# For Alpine/Debian minimal images, install CA certs
RUN apt-get update && apt-get install -y ca-certificates
# Or for Alpine:
RUN apk add --no-cache ca-certificates

# Or set an explicit bundle via env var
ENV SSL_CERT_FILE=/path/to/ca-bundle.pem

For explicit control in code:

import ssl
from openai import OpenAI, DefaultHttpx2Client

ssl_context = ssl.create_default_context(cafile="/path/to/ca-bundle.pem")
client = OpenAI(http_client=DefaultHttpx2Client(verify=ssl_context))

What I'd Have Done Differently

The migration is otherwise clean — same API, better maintainership (Pydantic is actively invested), and OS trust store is the right default for 80% of use cases. But the silent TLS change is the kind of "minor" dependency swap that causes production incidents. A deprecation warning in v3.4.x that logged "certifi will no longer be the default trust store in v3.5 — set SSL_CERT_FILE if you rely on it" would have saved a lot of 2am debugging.

The SDK does provide a temporary escape hatch — you can pass a legacy httpx Client via the old DefaultHttpxClient wrapper:

from openai import OpenAI, DefaultHttpxClient

# Legacy fallback — still works but will be removed
client = OpenAI(http_client=DefaultHttpxClient())

This is undocumented in the main migration doc, surfaced only in a commented-out code block. Use it as a bridge, not a solution.

Bottom Line

OpenAI SDK 3.5.0 is a solid dependency cleanup — dropping a stalled HTTP library, adopting OS-native TLS, and keeping full API compatibility. But the TLS trust store change is invisible until it breaks in production. If you deploy OpenAI-powered applications in Docker, test with python:3.13-alpine or distroless before the next deploy. Add ca-certificates to your Dockerfile. Set SSL_CERT_FILE if you use a custom bundle. And read changelogs — this one actually matters.