openai-python v3.0.0 の HTTPX2 移行を運用者目線で読む

v3.0.0 の破壊的変更は「HTTPX2 が既定 + httpx の自動インストール廃止」の 2 点

openai-python v3.0.0（2026 年 8 月 12 日リリース）の破壊的変更は、突き詰めると 2 つです。HTTP クライアントの既定が HTTPX2 に変わったこと、そして httpx が依存として自動でインストールされなくなったこと。この 2 点さえ押さえれば、あとは応用問題になります。

リリースノートの表現はそっけない。「HTTPX2 is now the default HTTP client, and httpx is no longer installed automatically」の一文が、破壊的変更セクションのほぼ全てです。実装は PR #3594 でまとまっていて、比較元は直前の安定版 v2.54.0。メジャーバージョンをひとつ上げるだけの update に見えて、custom HTTPX client / transport / configuration object（自前の HTTP クライアントや通信層の差し込み設定）を触っているアプリには移行作業が発生します。逆に、何もカスタムしていない素の OpenAI() 呼び出しだけなら、影響はほとんどありません。まずは「自分のコードが httpx を直接触っているか」を確認するのが最初の一歩です。

何が本当に壊れるのか — 消えた依存と TLS trust store の切り替え

一番刺さるのは、依存の消失と TLS の trust store（証明書の信頼元）の切り替えの 2 点です。どちらも「今まで動いていたのに急に落ちる」形で顕在化します。

まず依存。これまで pip install openai を打つと httpx も一緒に入っていましたが、v3.0.0 からは入りません。import httpx に依存していたコードは ModuleNotFoundError で落ちます。対処は素直で、明示的に足すだけです。

# httpx を直接使うなら明示的に入れる
pip install openai httpx
# aiohttp バックエンドを使う場合
pip install 'openai[aiohttp]'

より厄介なのが TLS です。HTTPX2 は証明書の検証に certifi の同梱バンドルではなく、OS の trust store を使います。ここが移行ガイドで一番の落とし穴で、certifi 前提で組まれた最小構成のコンテナや、企業プロキシで独自 CA を挟む環境では、証明書検証がいきなり失敗します。「ローカルでは通るのに CI と本番の distroless イメージだけ TLS エラー」という、原因の切り分けに時間を溶かす型の事故です。破壊的操作をコマンド単位で止める dcg を運用者目線で評価した話 と同じで、環境差で挙動が変わる変更こそ staging での事前確認が効きます。

custom client / transport / config を HTTPX2 へ移す

移行の型は決まっています。httpx. で始まるクラスを対応する httpx2. のクラスに置き換え、推奨設定は SDK 同梱の DefaultHttpx2Client に寄せる。ほぼこれだけです。

対応表はほぼ機械的に読めます。

移行前	HTTPX2
httpx.Client	httpx2.Client
httpx.Timeout	httpx2.Timeout
httpx.HTTPTransport	httpx2.HTTPTransport
httpx.MockTransport	httpx2.MockTransport

プロキシやタイムアウトを差し込みたいときは、自前で一から組むより、SDK が用意した DefaultHttpx2Client / DefaultAsyncHttpx2Client を使うのが安全です。既定値が SDK 側の推奨に揃うので、後追いで挙動がずれにくい。

import httpx2
from openai import OpenAI, DefaultHttpx2Client

client = OpenAI(
    http_client=DefaultHttpx2Client(proxy="http://proxy.example.com:8080"),
)

テストで MockTransport を使ってレスポンスをスタブしているコードは、httpx2.MockTransport に読み替えればそのまま動きます。SDK の内部依存を差し替えるという意味では、Anthropic SDK の managed agents / deployments を追った回 で見た「SDK の内部が変わると呼ぶ側の前提も変わる」構図の、HTTP レイヤ版だと言えます。

legacy escape hatch は「移行の時間を買う」ためだけに使う

急いで全部を移せないときのために、runtime 限定の legacy escape hatch（旧 httpx をそのまま渡す抜け道）が用意されています。ただしこれは恒久策ではなく、移行までの時間稼ぎと割り切って使うものです。

やり方は、cast() で型チェックを迂回して従来の httpx.Client を渡すだけです。

from typing import Any, cast
import httpx
from openai import OpenAI

# 型チェックを通すための cast。あくまで一時しのぎ
client = OpenAI(http_client=cast(Any, httpx.Client()))

移行ガイドはこの経路を "runtime-only" かつ "may be discontinued"（将来削除されうる）と明記しています。つまり「次のマイナー更新で消えても文句は言えない」道です。私はこれを、依存ピン留めを外す前の一時的な橋としてだけ使い、恒久コードには残さない方針にしました。escape hatch を本番に残すのは、非常口に鍵をかけて住み着くようなもので、いつか自分が閉じ込められます。

本番の受け止め方 — 依存をピン留めして段階移行する

結論から言うと、本番はまず openai<3 でピン留めして時間を止め、staging で HTTPX2 を通してから上げるのが安全です。メジャーバージョンの自動追従は、こういう時にだけ牙をむきます。

私は 2026 年 8 月の金曜の夜、手元の MacBook Air（M2）で openai==3.0.0 を staging コンテナに入れて試しました。素の chat 呼び出しは何事もなく通ったのに、certifi 前提で組んでいた distroless イメージだけが TLS 検証で落ち、原因にたどり着くのに小一時間かかりました。犯人が trust store の切り替えだと分かってからは、独自 CA を OS の trust store 側に入れ直して解決。ここで学んだのは、リリースノートの「HTTP client が変わった」の一行は、実運用では「証明書の載せ方が変わった」と読み替えるべきだ、ということでした。

手順としては、requirements で openai>=2.54,<3 に固定して本番を凍結し、別ブランチで httpx から httpx2 への置換と TLS の検証を staging で通し、問題が無ければピンを外して昇格する、の 3 段に分けます。これは AI が下書きを起こし、私が公開前に確認して出している当サイトの運用と同じで、いきなり本番に反映せず一段挟むだけで事故は目に見えて減ります。依存の更新は、動かなくなって初めてありがたみが分かる種類の作業でした。