claude-agent-sdkのwheelが公開されず、pip installに失敗する原因と対処法

「wheel for the current platform」エラーの内容

pip install claude-agent-sdk や uv add claude-agent-sdk が、特定のバージョンだけ「現在のプラットフォーム向けのwheelが無い」というエラーで失敗することがあります。原因は手元の環境ではありません。PyPIへの公開ジョブが途中で止まり、一部のプラットフォームのファイルしかアップロードされていない状態です。2026年3月のv0.1.49で実際に起きました。

uvでは、Linux環境で次のように止まります。

uv pip install claude-agent-sdk==0.1.49

error: Distribution `claude-agent-sdk==0.1.49 @ registry+https://pypi.org/simple`
can't be installed because it
doesn't have a source distribution or wheel for the current platform
hint: You're on Linux (`manylinux_2_39_x86_64`), but `claude-agent-sdk`
(v0.1.49) only has wheels for the following platform: `macosx_11_0_arm64`

pipでは表示が変わります。プラットフォーム不一致だけが原因なら、No matching distribution found for claude-agent-sdk==0.1.49 と出ます。from versions には他のバージョンが並び、指定した0.1.49だけが入っていません。

当時のv0.1.49には、macOS ARM64のwheelしかありませんでした。ソース配布物(sdist)も、Linux・Windows・macOS x86_64向けの4つのwheelも欠けていたため、ソースからのビルドに逃げる道もありません。issue #687の報告では、影響を受けたのはLinux(x86_64とaarch64)、Windows、macOS x86_64です。

被害はCI/CDで大きく出ました。バージョンを固定せず最新版に追従する構成では、デプロイのタイミングで突然ビルドが落ちます。報告者も、本番デプロイがこのエラーで失敗したと書いています。

原因はPyPIの容量上限で公開ジョブが止まったこと

issue #687の時点では、twine upload の2番目のファイルで 400 Bad Request が出て、残りのアップロードが止まったところまでしか分かっていませんでした。経緯が明らかになったのは、後続の修正PR(#700・#707)です。

実際の原因は、PyPI上のプロジェクト容量が当時の上限10GiBに達したことでした。1つ目のmacOS ARM64向けwheelは容量内に収まり、2つ目で上限を超え、ジョブ全体が止まりました。PyPIが返したのは汎用の 400 Bad Request だけで、容量超過を示す文言はありません。issueの報告者も、原因を「メタデータの不備か、重複の検出か、ファイルサイズの上限か」と推測するしかありませんでした。

復旧を難しくしたのが、PyPIの「同じファイル名は再アップロードできない」という仕様です。ワークフローを再実行すると、すでに載っている1つ目のファイルで twine が「file exists」のエラーを返し、残りを再送できません。

issueの報告者が出した選択肢は2つでした。v0.1.49を「yank」して仕切り直す方法と、PyPIが部分アップロードを許すなら残りだけを手で足す方法です。yankは、公開済みのファイルを消さずにインストールの候補から外す操作で、== で厳密に固定した場合を除き、その版は選ばれなくなります。実際に採られたのは、容量を広げたうえで元のワークフローを再実行し、同じ番号のまま欠けていたファイルを足す形でした。

症状に出会ったら、まず公開ファイルの一覧を見る

同じ症状に出会ったとき、先に疑う対象は手元の環境よりも、そのバージョンの公開が完了しているかどうかです。PyPIのJSON APIなら、バージョンごとのファイル名を直接取れます。

curl -s https://pypi.org/pypi/claude-agent-sdk/json \
  | python3 -c "import json,sys; d=json.load(sys.stdin); \
    print([f['filename'] for f in d['releases']['0.1.49']])"

現在のv0.1.49では、次の6ファイルが返ります。

['claude_agent_sdk-0.1.49-py3-none-macosx_11_0_arm64.whl',
 'claude_agent_sdk-0.1.49-py3-none-macosx_11_0_x86_64.whl',
 'claude_agent_sdk-0.1.49-py3-none-manylinux_2_17_aarch64.whl',
 'claude_agent_sdk-0.1.49-py3-none-manylinux_2_17_x86_64.whl',
 'claude_agent_sdk-0.1.49-py3-none-win_amd64.whl',
 'claude_agent_sdk-0.1.49.tar.gz']

障害の間は、このリストがmacOS ARM64のwheel 1件だけでした。wheelとsdistの数が前後のバージョンより明らかに少なければ、公開ジョブの途中失敗です。もう一つの手がかりは、そのバージョンのタグとGitHub Releaseが無いことでした。障害の間のv0.1.49は、この2つも欠けていました。

どこで落ちるかは、環境によって分かれます。

最初の行が最も紛らわしい点です。開発機で動いているので、CIの設定を疑いたくなります。

回避策は、動作確認済みの前のバージョンに固定することです。

# 問題のバージョンを除外して、直前の動作確認済みバージョンに固定する
pip install "claude-agent-sdk>=0.1.48,<0.1.49"

uvなら、pyproject.toml や uv add のバージョン指定で上限を切ります。ロックファイルを使っている構成では、公開直後の未完成なバージョンを自動では拾いません。ロックファイルの有無も合わせて見ておく価値があります。

2026年3月の障害後、公開パイプラインが強化された

障害の後、PyPIが返すファイル一覧は次のように変わりました。

macOS ARM64のwheelは、v0.1.48が57,559,306バイト、v0.1.49が57,620,663バイト、v0.2.153が90,323,861バイトです。macOS x86_64向けのwheelはv0.1.48にはなく、v0.1.49から加わっています。1バージョンで5つのwheelとsdistを送るため、容量の消費は版ごとに積み上がります。

同じJSONの upload_time(UTC)で、後から補われたかどうかを確かめられます。同じバージョンのファイルが3日も離れていれば、補完の印です。v0.1.49では、macOS ARM64のwheelが3月17日00:44、残りの5ファイルが3月20日です。

sdistを先に送る順序も、時刻に出ています。v0.1.50ではsdistが23:00:58、最初のwheelが23:01:01でした。v0.2.153でも、sdistが20:37:04で最初です。

復旧の裏では、もう一つの不具合が続いていました。再実行はバージョン番号を確定させるコミットを git push する段階で、他のコミットとの衝突により失敗しています。リポジトリ側の _version.py は0.1.48のままでした。そのため、CLI 2.1.78と2.1.79に追従する後続の自動リリースも「v0.1.49」を計算し、中身の違う同名ファイルをPyPIへ送り、400 Bad Request を返され続けました。PR #707がリポジトリ側の番号をPyPIの実態(0.1.49)に合わせて、ようやく解消しています。

再発防止は、PR #700で公開ワークフローに3つ入りました。

強化後の9月にも、同じ上限でリリースが止まった

事前チェックは、その後も実際に働いています。issue #1254によると、2026年9月9日にv0.2.153のリリースが「予測使用量47.567GiBが、安全閾値の47.5GiBを超える」という理由で公開前に止まりました。5種類のwheelのビルドはすべて成功していて、止まったのは公開の判断だけです。

3月と違うのは、止まる場所が公開の前だという点です。不完全なファイル一覧がユーザーの手元に届くことはありません。issueは9月23日にクローズされ、v0.2.153はPyPIで6ファイルすべてが公開されています。GitHub Releaseは9月15日20:38(UTC)、PyPIの6ファイルは20:37台のアップロードで、issueの報告から6日後です。

issueが求めたのは、容量の見直し、追加の容量か整理、そして再実行でした。3月のPR #700は、古いリリースの削除(PyPIのWeb画面での手作業)を対象外にしています。上限に近い状態は、その後も続いていたわけです。

閾値の47.5GiBは、PyPIの上限50GiBの95%にあたります。v0.2.153の予測使用量47.567GiBは、この線をわずかに超えていました。

似た別のエラーと混同しない — Pythonバージョン不一致との違い

pipやuvのインストールエラーには、原因の違う似たメッセージがあります。手元のPythonが、対応範囲の外にある場合です。pipはどちらの場合も No matching distribution found を返すため、この一行だけでは区別できません。違いは括弧内の from versions に出ます。claude-agent-sdk の最新版は Requires-Python >=3.10 を宣言しています。

どちらも最初に公開ファイル一覧と Requires-Python を並べて見れば分かれます。前者はPyPI側の状態が原因なので、バージョン固定で対処します。後者は手元の環境が原因で、Pythonのアップグレードが要ります。uvではplatformのhintが出るかも手がかりになります。

同様のエラーに遭遇したときの切り分け手順

claude-agent-sdk 以外のPyPIパッケージで「特定プラットフォームのwheelが無い」と出たときも、次の順で切り分けると早いです。

• PyPIの配布ファイル一覧を確認する。pypi.org/project/<パッケージ名>/<バージョン>/#files を開くか、JSON APIでファイル数を数える
• 直前のバージョンで同じ操作を試す。直前のバージョンで再現しなければ、環境ではなく該当バージョンの公開に問題がある
• 同じ問題を報告しているissueを検索する。パッケージ名と wheel や missing で、該当リポジトリのissueを探す
• OSSなら公開ワークフローの実行ログを見る。公開リポジトリのActionsタブで該当リリースの実行を開けば、どのステップで止まったかが分かる
• ロックファイルでバージョンを固定する。再現性が要るCI/CDは、公開直後のバージョンに自動追従しない設計にする

Agent SDKのインストールとセットアップの基本手順はClaude Agent SDK入門にあります。DockerのDEBUG環境変数でAgent SDKが動かなくなる別の既知バグはAgent SDKがDockerのDEBUG環境変数で動かなくなる原因と回避策、並列ツール呼び出しに起因するMCP接続エラーはMCP Stream closedエラーはAgent SDKの並列呼び出しで起きるで扱っています。ストリーミングモードでサブエージェントを使うときのエラーはonly prompt commands are supportedエラーの原因、レート制限イベント周りのパースエラーはrate_limit_eventでMessageParseErrorが発生し停止する原因と対処が参考になります。

まとめ

特定バージョンだけ「wheelが無い」で失敗するなら、手元の設定をいじる前にPyPIのファイル一覧を数えるのが最短です。前後のバージョンより数が少なければ公開側の問題なので、前のバージョンへ固定して復旧を待ちます。ロックファイルがあれば、この種の事故はデプロイ時に表に出ません。