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でこの状態が発生しました。

Linux環境での再現はこうなります。

pip install claude-agent-sdk==0.1.49

error: Distribution `claude-agent-sdk==0.1.49` 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`

このバージョンはmacOS ARM64のwheelだけがPyPIに存在し、ソース配布物(sdist)とLinux / Windows / macOS x86_64向けの4つのwheelが欠けていました。Intel Macのユーザーからも同時期に同じ症状が報告されています。影響を受けたのは新規インストールだけではありません。バージョンを固定せず最新版に追従するCI/CDパイプラインでは、デプロイのタイミングで突然ビルドが落ちる形で表面化しました。

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

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

実際の原因はPyPI側のプロジェクト容量が当時の上限だった10GiBに達したことでした。1つ目のmacOS ARM64向けwheelは容量内に収まりアップロードに成功しましたが、2つ目のファイルで上限を超え、公開ジョブ全体が止まりました。PyPIのエラーメッセージには容量超過を示す文言がなく、開発者はしばらく原因を「メタデータの問題」と推測していました。

さらに、いったんアップロード済みのファイルがあると、同じファイル名で再アップロードはできないというPyPIの仕様が復旧を難しくしました。ワークフローを再実行しても、既に成功した1個目のファイルで twine がエラーを返し、残り5個のファイルを再送できない状態が続きました。

issueの報告者は、この状態を抜け出す選択肢として2つを提案していました。1つはv0.1.49を「yank」した上でv0.1.50として仕切り直す方法です。yankはPyPI用語で、公開済みのファイルを削除せずに「新規インストールの候補から外す」印を付ける操作で、バージョンを名指しでピン留めしている既存ユーザーには影響しません。もう1つは、PyPIが同一バージョンへの部分アップロードを許すなら残り5ファイルだけを手動で追加する方法です。実際に採られたのは後者に近い形で、v0.1.49という番号のまま欠けていたファイルが追加されています。

対処法 — 前のバージョンに固定するか、公開ファイルを確認する

同じ症状に遭遇した場合、まず疑うべきは自分の環境ではなく、そのバージョンの公開が完了しているかどうかです。PyPIの公開ページには、そのバージョンに実際にアップロードされたファイルの一覧が出ます。

# 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']])"

wheelやsdistの数が明らかに少ない(1〜2個しかない)場合は公開ジョブの途中失敗を疑えます。回避策は、直前の動作確認済みバージョンにピン留めすることです。

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

uvを使っている場合も同様に、pyproject.toml や uv add のバージョン指定で上限を切ります。CI/CDパイプラインでバージョンを固定していない構成では、この種の公開ジョブの失敗が本番デプロイの直前で突然表面化しやすいため、依存関係のロックファイルを使っているかどうかも合わせて確認する価値があります。

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

v0.1.49の障害はどう決着したのか、実際のファイル配布状況を今回あらためてPyPIのAPIで確認しました。結論としては、3日後の3月20日に完全復旧しています。

PyPIの容量上限が10GiBから50GiBに引き上げられたことで、残りのファイルは再アップロードできるようになりました。復旧作業ではもう一段厄介な事情も判明しています。バージョン番号をリポジトリ側で確定させるコミットが git push の衝突で失敗し、そのままでは反映されませんでした。結果として、CLI 2.1.78・2.1.79向けの後続の自動リリースも _version.py の値を古いまま読み取り、毎回同じ「v0.1.49」を計算しました。中身の異なる同名ファイルをPyPIに送ることになるため、400 Bad Request を返され続ける二次的な不具合が続きました。この状態は、バージョン番号をPyPI上の実態に合わせ直す別PRでようやく解消しています。

再発防止として、公開ワークフローには3つの変更が加えられました。既にアップロード済みのファイルはエラーにせず飛ばす--skip-existingオプション、どのファイルが失敗しても最低限ソースからのビルドが効くようにsdistを最初にアップロードする順序変更、そしてPyPIの使用量が上限の95%を超えたら公開前に停止する事前チェックです。

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

この事前チェックは、直近でも実際に機能しています。2026年9月9日、v0.2.153のリリースが「使用量の予測が47.567GiBで、安全閾値の47.5GiBを超える」という理由で公開前に止まったと、GitHub issue #1254で報告されました。5種類のwheelビルド自体はすべて成功しており、公開判断だけが保留された形です。

このバージョンはPyPI側に6ファイルすべてが公開済みで、issueはクローズされていないものの実害は解消しています。3月の障害とは異なり、今回は不完全な状態でユーザーの手元に届く前に止まった点が変わっています。裏を返せば、PyPIの保存容量はこのSDKにとって恒常的な制約であり、今後も同種の一時停止が起こり得る構造だということです。

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

pipやuvが返すインストールエラーには、原因が違う似たメッセージがもう一つあります。手元のPythonが古すぎて対応バージョンの範囲外になっている場合のエラーです。

前者はPyPI側の状態が原因なので、公開ファイル一覧の確認とバージョン固定で対処します。後者は自分の環境側が原因なので、Pythonのアップグレードが必要です。エラーメッセージに「platform」の語が入っているかどうかで見分けられます。

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

claude-agent-sdk に限らず、PyPI経由のパッケージで「特定プラットフォームのwheelが無い」というエラーが出たときは、次の順で切り分けると早いです。

• PyPIの配布ファイル一覧を確認する。pypi.org/project/<パッケージ名>/<バージョン>/#files を開くか、JSON APIでファイル数を数える
• 直前のバージョンで同じ操作を試す。直前バージョンで問題が再現しなければ、環境ではなく該当バージョンの公開に問題がある
• 同じ問題を報告しているissueが無いか検索する。パッケージ名と wheel や missing で該当リポジトリのissueを検索する
• OSSならGitHub Actionsの実行ログを見る。公開ワークフローが公開リポジトリにある場合、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が発生し停止する原因と対処を参照してください。

まとめ

claude-agent-sdk のインストールが特定バージョンだけ「wheelが無い」で失敗する場合、原因の多くは自分の環境ではなくPyPI側の公開ジョブの途中失敗です。2026年3月のv0.1.49障害はPyPIの容量上限(当時10GiB)によるもので、3日で復旧し、再発防止として事前の容量チェックが公開パイプラインに組み込まれました。ただし9月にも同じチェックがv0.2.153のリリースを止めており、容量制約そのものはまだ解消されていません。同様のエラーに遭遇したら、まずPyPIの配布ファイル一覧を確認し、直前バージョンへの一時的な固定で切り抜けるのが確実です。