Poetry環境でのnumpyビルドエラーとバージョン制約による解決メモ#
Windows上で、Gitから取得したPythonプロジェクトを poetry install した際に、numpy のビルドに失敗する事象に遭遇した。Poetry環境でのエラーでありながら、原因は numpy のビルド処理にあった。
以下に、再現環境と解決までの経緯を記録しておく。
事象概要#
pyproject.toml に以下のような記述があった。
[tool.poetry.dependencies]
numpy = "^1.26.0"
この指定は SemVer の仕様に基づき、以下の範囲を意味する。
>=1.26.0, <2.0.0
このとき poetry install により、numpy==1.26.4 が選ばれた。しかし、ビルド済みホイール (.whl) が解決されず、Poetry 経由でのインストール時にソースビルドが開始され、Visual C++ Build Tools の導入等を実施しても not supporting PEP 517 builds などのエラーで失敗した。
対応内容#
Poetryの依存定義を以下のように修正：
numpy = "<=2.2.4"
これにより、Poetryは numpy==2.2.x 系のビルド済みバイナリを選択し、ビルド処理が不要となり、エラーが解消した。
背景と考察#
Poetryは pyproject.toml の内容や poetry.lock に基づき依存を解決するが、場合によってはビルド処理を行うパッケージを選択することがある。
numpy 1.26系は、バイナリを配布していた時期はあったはずだが、現状はバイナリ配布がないようで、ビルドが発生。
numpy 2.2系はホイール配布も安定しており、特にWindows環境ではビルドなしで導入できるケースが多い。
^1.26.0 のような記述は保守的であるが、状況によっては逆に問題を引き起こすこともある。
今後の教訓#
同様の問題に遭遇した際は、以下の観点で早期に切り分けを行う：
PEP 517 ビルドなどのお作法の変更に伴うエラーかどうかを確認
必要に応じてバージョンを変更し、より新しい安定版を利用する
補足：numpy の非互換について#
numpy==2.0.0 以降では、一部破壊的変更が入っているため、依存する他ライブラリとの互換性に注意。必要に応じて >=1.26,<2.0 のような上限制約も有効。
記事情報
- 著者:
mtakagishi
- 公開日:
2025-07-26