最近、Pythonでアプリを作っていると、今まで動いていたコードが急にエラーになることがあります。 その原因のひとつとして疑いたいのが、NumPy 2.0系への更新です。
NumPy 2.0は大きなメジャーアップデートで、NumPy公式のリリースノートでも breaking changes や ABIの破壊的変更 が案内されています。 そのため、NumPy本体だけでなく、NumPyに依存する周辺ライブラリとの組み合わせで不具合が出やすくなりました。
参考：
NumPy公式｜NumPy 2.0.0 release notes
NumPy公式｜NumPy 2.0 migration guide
そのため、非エンジニアがClaude CodeなどのAIツールを使って まず安定して動くPythonアプリを作りたいなら、 最初から Python 3.11＋NumPy 1.26系 を指定して進めるのはかなり現実的な考え方です。 この記事では、その理由と、Claude Codeにどう指示すると進めやすいかを整理します。
なぜNumPy 2.0で不具合が出やすいのか
NumPy 2.0は、単なる機能追加レベルの更新ではありませんでした。 公式リリースノートでは、通常のマイナーアップデートでは入らないような 大きな破壊的変更 が含まれていることが明記されています。
さらに、NumPy公式の移行ガイドでは、NumPy 2.0への対応には Python API と C API の両面で見直しが必要になることが説明されています。 加えて、NumPyは binary compatibility も壊れる と案内しており、 NumPyのC APIに依存するパッケージでは、NumPy 2.0向けに再ビルドされた配布物が必要になるケースがあります。
参考：
NumPy公式｜NumPy 2.0.0 release notes
NumPy公式｜NumPy 2.0 migration guide
NumPy公式｜For downstream package authors
つまり、NumPy 2.0でエラーが増えやすいのは、 NumPy 2.0自体が「不安定だから」というより、 周辺ライブラリや既存コードとの互換性問題が起きやすいタイミングだからです。 特に非エンジニアがアプリを作る場合は、こうした依存関係の地雷を自力で追うのがかなり大変です。
なぜPython 3.11＋NumPy 1.26構成を試すのか
ここで候補になるのが、Python 3.11＋NumPy 1.26系です。
まずPython 3.11系は、2026年3月時点で security fixes only の段階に入っています。 Python公式では、3.11系はすでに通常のbugfixフェーズを終えており、 以後はセキュリティ修正中心のリリースになると案内されています。 また、Python 3.11.9 が最後のフルbugfixリリースで、以後の 3.11.11 や 3.11.15 などは source release中心で提供されています。
参考：
Python公式｜Python 3.11.9
Python公式｜Python 3.11.11
Python公式｜Python 3.11.15
Python Developer’s Guide｜Status of Python versions
つまりPython 3.11は「最新」ではありませんが、 すでに広く使われ、周辺ライブラリとの相性も比較的読みやすいラインです。
次にNumPy 1.26系は、NumPy 1.x系の後期ラインとして使われてきたバージョンです。 PyPIでも NumPy 1.26.4 が公開されており、 NumPy 2.0移行前後の比較対象として扱いやすいバージョンです。
そのため、 とにかくまず動かしたい、 依存関係のトラブルを減らしたい、 Claude Codeに安定重視で依頼したい という状況では、 Python 3.11＋NumPy 1.26系に寄せるのはかなり実用的です。
最初に知っておきたい注意点
ここでひとつ大事なのは、 Python 3.11＋NumPy 1.26 が絶対の正解ではないということです。
すでに利用したいライブラリがNumPy 2.x前提になっている場合は、 NumPy 1.26へ戻すだけでは解決しません。 また、Python 3.11系は2026年3月時点で通常のbugfixフェーズを終えているため、 新規に環境を用意する方法は使う配布元によって少し差があります。
それでも、非エンジニアがまずローカルで安定稼働を目指すなら、 最初の構成を保守的にするという考え方はかなり有効です。
Claude Codeには最初から環境条件を明示する
Claude Codeに 「エラーが出ないようにして」 だけを伝えると、最新バージョンをそのまま使う方向に寄ることがあります。 そのため、環境条件は最初からはっきり書いた方が安全です。
たとえば、次のような依頼文が使えます。
このアプリは安定稼働を優先したいです。
Python は 3.11 系を前提にしてください。
NumPy は 2.x ではなく 1.26 系を使ってください。
必要なら仮想環境を作成し、requirements.txt か pyproject.toml に
バージョン制約を明記してください。
まずはコードを書き換える前に、
現在の依存関係で NumPy 2.x が入る可能性があるか確認し、
安定構成にする方針を提案してください。この依頼のポイントは、
- 安定稼働を優先すること
- Python 3.11系を前提にすること
- NumPy 1.26系を使うこと
- いきなり実装せず、まず依存関係を確認させること
を最初に明文化している点です。 こうしておくと、Claude Codeが勝手に最新構成へ寄せすぎるのを防ぎやすくなります。
requirements.txt でNumPy 2.0系を避ける方法
たとえば requirements.txt を使うなら、 もっともわかりやすいのは次のように固定する方法です。
numpy==1.26.4NumPy 1.26.4 はPyPIで公開されている1.26系のリリースです。
少し幅を持たせたいなら、以下のような書き方もあります。
numpy>=1.26,<2この書き方なら、NumPy 2.xへの更新を避けながら1.x系にとどめられます。 ただし、ほかの依存ライブラリがNumPy 2.xを要求している場合は、 この指定だけでは解決しないこともあります。
Claude Codeへの依頼プロセス例
私なら、Claude Codeには次の順番で依頼します。
1．まずは調査だけ依頼する
このプロジェクトの依存関係を確認して、
NumPy 2.x が原因になりそうな箇所を洗い出してください。
コード変更はまだ不要です。
Python 3.11 + NumPy 1.26 系に寄せる場合の修正方針を提案してください。2．安定構成へ寄せる作業を依頼する
では安定稼働を優先して、
Python 3.11 を前提に仮想環境構成を整理し、
NumPy は 1.26 系に固定してください。
requirements.txt または pyproject.toml に反映してください。3．最後に変更内容を説明してもらう
変更後に、
- どのファイルを修正したか
- NumPy 2.x を避けるために何をしたか
- ローカルで確認する手順
を簡潔にまとめてください。この流れにすると、非エンジニアでも 「何が変わったのか」 「何のための修正なのか」 を追いやすくなります。
NumPy 2.0系を完全に避けるべきなのか
ここも誤解しやすいポイントです。 NumPy 2.x 系は現在も継続して更新されていて、PyPI上でも 2.2.4 などのリリースが確認できます。 つまり、長期的には周辺ライブラリの対応が進めば、NumPy 2.x を使うのが自然な場面も増えていきます。
ただし、非エンジニア向けの記事として大事なのは、 最新を追うことより、まず安定して動くことです。 特に画像処理、データ処理、機械学習まわりのライブラリを組み合わせるときは、 NumPy 2.0移行が原因で思わぬエラーに出会うことがあります。
そのため、最初の一歩として Python 3.11＋NumPy 1.26系 を試す、という方針は十分に合理的です。
まとめ｜安定稼働を優先するならまずは保守的な構成から
NumPy 2.0で不具合が出やすい背景には、 NumPy公式でも案内されている breaking changes と binary compatibilityの変化 があります。 そのため、周辺ライブラリとの組み合わせ次第では、思った以上にエラーが起こりやすくなります。
そんなとき、非エンジニアがまず試しやすいのが、
- Python 3.11系を前提にする
- NumPy 1.26系へ固定する
- requirements.txt や pyproject.toml に明記する
- Claude Codeには最初から「安定稼働優先」と伝える
という進め方です。
もちろん、将来的にはNumPy 2.xへ移行していく場面も出てきます。 ただ、まずアプリを安定して動かしたい段階では、 保守的な構成をAIに明示して進めることが、かなり大きな助けになります。
コメント