numpy build error in Poetry environment and resolution notes due to version constraints#
When I tried poetry install on a Python project obtained from Git on Windows, I encountered an issue where numpy build failed. Although the error occurred in the Poetry environment, the cause was in the numpy build process.
Below is a record of the reproduction environment and the process leading up to the resolution.
Event summary#
There was a description like the following in pyproject.toml.
[tool.poetry.dependencies]
numpy = "^1.26.0"
This designation is based on the SemVer specifications and means the following range.
>=1.26.0, <2.0.0
At this time, numpy==1.26.4 was selected by poetry install. However, the pre-built wheel (.whl) was not resolved, a source build was started when installing via Poetry, and even after installing Visual C++ Build Tools, it failed with an error such as not supporting PEP 517 builds.
Compatible content#
Modify the Poetry dependency definition as follows:
numpy = "<=2.2.4"
As a result, Poetry selected pre-built binaries of the numpy==2.2.x series, eliminating the need for a build process and eliminating the error.
Background and considerations#
Poetry resolves dependencies based on the contents of pyproject.toml and poetry.lock, but in some cases it may choose a package to perform the build process.
There must have been a time when numpy 1.26 series distributed binaries, but currently it seems that there is no binary distribution, so a build occurs.
numpy 2.2 series has stable wheel distribution, and in many cases it can be installed without building, especially in Windows environments.
Although a description like ^1.26.0 is conservative, it can actually cause problems depending on the situation.
Lessons for the future#
When you encounter a similar problem, isolate it early based on the following points:
Check whether the error is due to a change in manners such as PEP 517 build.
Change the version if necessary to use a newer stable version
Supplement: Regarding numpy incompatibility#
Since numpy==2.0.0 contains some breaking changes, be careful about compatibility with other dependent libraries. Upper constraints such as >=1.26,<2.0 are also valid if necessary.
Article information
- author:
Mr. Takagi
- Release date:
2025-07-26