OpenAI Python SDK 3.0 dropped certifi on 12 August 2026 and broke TLS in slim containers
Summary. The openai Python package shipped 6 releases between 11 and 19 August 2026, and version 3.0.0, published to PyPI at 01:55 UTC on 12 August 2026, is a breaking one. It swapped HTTPX for HTTPX2, the Pydantic team's rewrite, and stopped installing certifi. Certificate verification now goes through the operating-system trust store. The dependency list for openai 3.3.1 pins exactly one HTTP dependency, httpx2<3,>=2.7.0, with aiohttp>=3.14.3 only under the optional aiohttp extra, and a floor of Python 3.10. That change reaches applications that never configured an HTTP client at all. At GPT-5.6 Sol list prices of $5.00 per 1M input tokens and $30.00 per 1M output tokens on the Standard tier, a fleet that cannot complete a TLS handshake is not spending anything, which is the only good news here.
The second problem is where the change was announced. OpenAI's platform changelog carries 7 entries for August 2026, dated the 4th, 5th, 6th, 7th, 13th and two on the 20th. None of them mentions version 3.0.0, HTTPX2, certifi, or any of the six SDK releases. The only place the change is written down is the package's CHANGELOG.md and a migration guide at httpx2.md in the repository. A team that watches the official changelog and pins with a caret or a >= range got the change without a notice.
What actually changed
The openai client's public surface is intact. Parsed response models, streaming APIs, authentication, retries and numeric timeout values all behave as before, and existing string URLs do not change. The migration guide is explicit that an application constructing OpenAI() or AsyncOpenAI() without an http_client argument keeps working.
The transport underneath is a different library. HTTPX2 lives at pydantic/httpx2 and describes itself as "A next-generation HTTP client for Python." Installing openai no longer installs httpx. Code that imported httpx because an earlier SDK pulled it in transitively now fails at import time until you add your own httpx dependency or move those imports to httpx2.
| Behaviour | openai 2.54.0 and earlier | openai 3.0.0 and later |
|---|---|---|
| HTTP client library |
httpx, installed transitively |
httpx2, pinned <3,>=2.7.0
|
| TLS trust store |
certifi CA bundle, installed by the SDK |
Operating-system trust store; certifi not installed |
| aiohttp support | External httpx-aiohttp adapter |
HTTPX2-native transport under the aiohttp extra |
| Raw response type | httpx.Response |
httpx2.Response |
| Type-checked custom client |
httpx.Client accepted |
Only HTTPX2 clients pass mypy and Pyright |
The part that breaks without you touching anything
Read this sentence from the migration guide twice: "HTTPX2 changes the default TLS trust store, including for applications that use the SDK's default HTTP client."
HTTPX previously verified certificates against the CA bundle shipped by certifi. HTTPX2 uses the operating-system trust store instead, and the SDK no longer installs certifi at all. The guide names three environments where that fails:
Minimal container images with no system CA certificates. A scratch, distroless or stripped Alpine image that worked because certifi carried its own bundle inside the Python site-packages directory now has nothing to verify against.
Environments behind corporate TLS-inspecting proxies. The proxy's signing certificate has to be in the OS trust store now, not in a Python package.
Deployments that relied on a custom or modified certifi bundle. Patching certifi was always ugly, and plenty of regulated environments did it anyway. That mechanism is gone.
The failure mode is a certificate verification error on the first API call in production, not at build time and not in tests that run on a developer laptop with a populated macOS or Debian trust store. That gap between where it passes and where it fails is what makes this expensive.
What to change, and in what order
Install the CA certificates into the operating-system trust store, or point the process at an explicit bundle. HTTPX2 honours SSL_CERT_FILE and SSL_CERT_DIR when trust_env=True, which is the default:
export SSL_CERT_FILE=/path/to/ca-bundle.pem
For explicit control on a custom client, pass an ssl.SSLContext through verify:
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))
DefaultAsyncHttpx2Client(verify=ssl_context) is the async equivalent, and the SDK's aiohttp transport uses the same HTTPX2 TLS settings.
If you inject a custom HTTP client, every HTTPX object has an HTTPX2 counterpart with the same name: httpx.Client becomes httpx2.Client, and the same one-to-one mapping applies to AsyncClient, Timeout, URL, Limits, HTTPTransport, AsyncHTTPTransport and MockTransport. The older DefaultHttpxClient and DefaultAsyncHttpxClient names still resolve, but they now construct HTTPX2 clients, so a name that reads as unchanged in your codebase is doing something different. Custom transport subclasses, mounted transports, proxy integrations and connection-pool instrumentation have to target HTTPX2's transport interfaces. Authentication handlers and event hooks receive HTTPX2 request and response objects.
Test suites are the second landmine. Mocks must intercept HTTPX2 requests and return HTTPX2 responses. The guide states plainly that a RESPX version patching only legacy HTTPX "cannot intercept the SDK's default HTTPX2 client," so a suite that green-lights the upgrade may simply be mocking a client that is no longer in the request path.
There is an escape hatch, and it is deliberately uncomfortable. Install legacy HTTPX yourself and inject it:
from typing import Any, cast
import httpx
from openai import OpenAI
client = OpenAI(http_client=cast(Any, httpx.Client()))
Legacy HTTPX support is runtime-only. The SDK's public type annotations accept HTTPX2 clients, so passing a legacy client fails static type checking in mypy and Pyright without a cast or a targeted ignore. The guide adds that legacy support "is provided as a migration aid and may be discontinued." Treat it as a two-week bridge, not a decision.
The rest of the wave
Version 3.0.0 was not the end of it. Five more releases followed in seven days, and each carries something a platform team needs to know about.
| Version | PyPI publish time (UTC) | What it carries |
|---|---|---|
| 2.54.0 | 2026-08-11 18:46 | New Responses model identifiers; audio upload metadata fix |
| 3.0.0 | 2026-08-12 01:55 | HTTPX2 default; httpx and certifi no longer installed |
| 3.1.0 | 2026-08-14 23:49 | Sora video APIs deprecated; Ultrafast tier; WebSocket stream IDs |
| 3.2.0 | 2026-08-17 19:14 | Bedrock Runtime endpoint support (SDK-290) |
| 3.3.0 | 2026-08-18 21:17 | Named data-residency endpoints; patched optional networking deps |
| 3.3.1 | 2026-08-19 16:31 | Dependency updates with published security fixes (#3680) |
Two of those deserve separate attention. Release 3.1.0 deprecates the Sora video APIs, and OpenAI's deprecations page sets the shutdown date for the Videos API and for sora-2, sora-2-pro, sora-2-2025-10-06, sora-2-2025-12-08 and sora-2-pro-2025-10-06 at 24 September 2026. Release 3.3.0 adds support for named data-residency endpoints, which matters to anyone who has been reading residency scope out of documentation rather than out of the client.
The 3.1.0 release also added types for the Ultrafast tier, which OpenAI announced on 13 August 2026 as a service tier for GPT-5.6 Sol running "up to 14x faster than Standard processing," in limited preview to selected customers. No price is published for Ultrafast. The tier below it is priced: Fast mode for GPT-5.6 Sol costs $10.00 per 1M input tokens and $45.00 per 1M output tokens against $5.00 and $30.00 on Standard, as listed on 21 August 2026. If you are already reasoning about tier economics, our note on the Fast mode migration and the prompt caching dashboard covers where the cached-input rate changes the arithmetic.
The Node SDK did not take the same hit. openai-node 7.5.0, released 17 August 2026, adds Bedrock Runtime endpoint support, the Sora deprecation and the Ultrafast tier, with no HTTP client swap. This is a Python-only migration.
How to tell if this is you
Run three checks before the next deploy.
Check whether certifi is still in your image for another reason. pip show certifi inside the built container answers it. If another dependency pulls it in, HTTPX2 still will not use it, because the switch is to the OS trust store, not to a different Python bundle.
Check whether your base image has system CA certificates. On Debian and Ubuntu bases that is the ca-certificates package. Distroless and scratch images generally do not have it unless you copied it in.
Check whether your test suite actually exercises the transport. If it uses RESPX against legacy HTTPX, the upgrade will pass CI and fail in the first environment with a TLS-inspecting proxy.
Teams running this migration alongside the Assistants API removal on 26 August 2026 are doing two unrelated cutovers in the same fortnight, which is worth sequencing deliberately. Our OpenAI model shutdown migration map and the OpenAI agent API selection note cover that side of it.
What is still unknown
OpenAI has not said how long legacy HTTPX injection will be supported beyond "may be discontinued." There is no published price for the Ultrafast tier and no stated date for general availability. And there is no indication that the platform changelog will start carrying SDK releases, which means the GitHub CHANGELOG remains the only reliable watch point for breaking client changes. Pin an exact version, watch the repository, and stop treating the platform changelog as complete.
FAQ
Does OpenAI Python SDK 3.0.0 break my API calls?
No. Parsed response models, streaming, authentication, retries and numeric timeout values are unchanged, and existing string URLs still work. What changes is the transport layer underneath. The break is in TLS certificate verification and in any code that imported httpx, custom transports or mocks tied to the old client.
Why does dropping certifi matter if I never configured TLS?
Because HTTPX2 verifies certificates against the operating-system trust store rather than the certifi bundle, and the SDK no longer installs certifi. An application using the default client inherits the new behaviour. Minimal container images without system CA certificates will fail certificate verification on the first live API call.
What is HTTPX2 and who maintains it?
HTTPX2 is a next-generation HTTP client for Python published by the Pydantic team at the pydantic/httpx2 repository, with documentation at httpx2.pydantic.dev. The openai package version 3.3.1 pins it as httpx2 greater than or equal to 2.7.0 and below 3, and it is the only HTTP dependency installed.
How do I fix certificate verification in a slim container?
Install the CA certificates into the operating-system trust store, or set SSL_CERT_FILE or SSL_CERT_DIR to an explicit bundle. Both variables are honoured when trust_env is True, which is the default. For per-client control, pass an ssl.SSLContext through the verify argument on DefaultHttpx2Client or DefaultAsyncHttpx2Client.
Can I keep using the old HTTPX client?
Yes, temporarily. Install httpx yourself and inject it, wrapping the client in cast to Any because the SDK's type annotations only accept HTTPX2 clients. The migration guide describes this path as runtime-only and says legacy support is a migration aid that may be discontinued, so plan the real migration.
Will my test suite catch this before production?
Probably not. Mocks have to intercept HTTPX2 requests and return HTTPX2 responses. A RESPX version that patches only legacy HTTPX cannot intercept the SDK's default client, so the suite passes while the real transport goes unexercised. Update RESPX to an HTTPX2-compatible version before trusting the result.
Does the Node SDK have the same problem?
No. The openai-node 7.5.0 release of 17 August 2026 adds Bedrock Runtime endpoint support, the Sora video API deprecation and the Ultrafast tier, with no change of HTTP client. The HTTPX2 migration and the certifi removal apply only to the Python package.
How eCorpIT can help
This is a small change with a wide blast radius, and the work is mostly auditing container images and test harnesses rather than rewriting application code. eCorpIT runs senior-led Python platform engineering teams and is CMMI Level 5 and ISO 27001:2022 certified, which matters when the migration touches certificate handling in a regulated environment. If you want the audit run against your images and CI before the next deploy, talk to us or look at how we staff dedicated development teams.
References
- openai-python CHANGELOG.md - release notes for 2.54.0 through 3.3.1, including the 3.0.0 breaking-change notice.
- Migrating to HTTPX2 - the SDK's migration guide, including the TLS trust-store warning and the legacy escape hatch.
- openai on PyPI - published release history and the dependency pin on httpx2 below 3 and at least 2.7.0.
- OpenAI API changelog - the seven August 2026 platform entries, none of which mention the SDK releases.
- OpenAI API deprecations - the 24 September 2026 shutdown for the Videos API and the sora-2 snapshots, and the 26 August 2026 Assistants API removal.
- OpenAI API pricing - GPT-5.6 Sol Standard and Fast mode rates per 1M tokens.
- HTTPX2 documentation - the Pydantic project behind the new client.
- openai-node CHANGELOG.md - the 7.5.0 release of 17 August 2026, with no HTTP client change.
- openai-python pull request 3594 - the HTTPX2 migration commit behind version 3.0.0.
- openai-python issue 3680 - the dependency security fixes shipped in 3.3.1 on 19 August 2026.
- openai-python pull request 3646 - named data-residency endpoint support added in 3.3.0.
- openai-python pull request 3651 - the requirement for patched optional networking dependencies.
Last updated 21 August 2026.
Top comments (0)