numpy.distutils 状态和迁移建议#

numpy.distutils 已在 NumPy 1.23.0 版本中弃用。它将在 Python 3.12 中移除；对于 Python <= 3.11，它将在 Python 3.12 发布后 2 年（2025 年 10 月）移除。

警告

numpy.distutils 仅与 setuptools < 60.0 测试过，更新版本可能会导致其损坏。详情请参阅 numpy.distutils 与 setuptools 的交互。

迁移建议#

有几种优秀的构建系统可供迁移。假设您的包中包含编译代码（如果不是，您有几种不错的选择，例如 Poetry、Hatch 或 PDM 提供的构建后端），并且您希望使用设计良好、现代化且可靠的构建系统，我们推荐

Meson，以及 meson-python 构建后端
CMake，以及 scikit-build-core 构建后端

如果您需求不多（仅简单的 Cython/C 扩展；不需要 Fortran、BLAS/LAPACK、嵌套的 setup.py 文件或 numpy.distutils 的其他功能），并且一直对 numpy.distutils 感到满意，您也可以考虑切换到 setuptools。请注意，numpy.distutils 的大部分功能不太可能被移植到 setuptools。

迁移到 Meson#

SciPy 已在其 1.9.0 版本中迁移到 Meson 和 meson-python。在此过程中，Meson 的 Python 支持和与 numpy.distutils 的功能对等性方面的遗留问题得到了解决。*注意：对等性意味着一个较大的超集（因为 Meson 是一个通用的优秀构建系统）；仅缺少少数 BLAS/LAPACK 库选择的便利功能*。SciPy 使用 numpy.distutils 提供的几乎所有功能，因此如果 SciPy 已成功使用 Meson 作为构建系统发布，那么迁移应该没有障碍，SciPy 将是其他正在迁移的包的一个很好的参考。有关 SciPy 迁移的更多详细信息，请参阅

NumPy 将在 1.26 版本中迁移到 Meson。

迁移到 CMake / scikit-build#

下一代 scikit-build 称为 scikit-build-core。旧的 scikit-build 使用 setuptools 作为底层，而重写版本则不使用。与 Meson 一样，CMake 是一个通用的优秀构建系统。

迁移到 setuptools#

对于仅出于历史原因使用 numpy.distutils，但实际上不使用 setuptools 也支持的功能的项目，迁移到 setuptools 可能是最省力气的解决方案。为了评估这一点，列出 numpy.distutils 中 *不* 存在于 setuptools 中的功能：

嵌套的 setup.py 文件
Fortran 构建支持
BLAS/LAPACK 库支持（OpenBLAS、MKL、ATLAS、Netlib LAPACK/BLAS、BLIS、64 位 ILP 接口等）
对其他一些科学库的支持，如 FFTW 和 UMFPACK
更好的 MinGW 支持
每个编译器的构建标志自定义（例如，默认使用 -O3 和 SSE2 标志）
一个简单的用户构建配置系统，请参阅 site.cfg.example
SIMD 内建函数支持
对 NumPy 特定的 .src 模板格式支持，用于 .c/.h 文件

最广泛使用的功能是嵌套的 setup.py 文件。此功能将来也许仍会被移植到 setuptools（但这需要一个志愿者，有关状态，请参阅 gh-18588）。仅使用此功能的项目，在功能移植完成后可以迁移到 setuptools。如果一个项目只使用了几个 setup.py 文件，那么将这些文件的所有内容合并到一个 setup.py 文件中，然后迁移到 setuptools，也是一个可行的方案。这涉及到放弃所有 Configuration 实例，而是使用 Extension。例如：

from distutils.core import setup
from distutils.extension import Extension
setup(name='foobar',
      version='1.0',
      ext_modules=[
          Extension('foopkg.foo', ['foo.c']),
          Extension('barpkg.bar', ['bar.c']),
          ],
      )

更多详情，请参阅 setuptools 文档

numpy.distutils 与 setuptools 的交互#

建议使用 setuptools < 60.0。更新版本可能也能工作，但不能保证。原因是 setuptools 60.0 启用了 distutils 的内置副本，包括影响 numpy.distutils 中某些功能的向后不兼容更改。

如果您只使用简单的 Cython 或 C 扩展，并且除嵌套的 setup.py 文件（其最受欢迎的功能，请参阅 Configuration）之外，对 numpy.distutils 功能的使用很少，那么最新的 setuptools 可能会继续工作。如果出现问题，您也可以尝试 SETUPTOOLS_USE_DISTUTILS=stdlib 来避免 setuptools 中的向后不兼容更改。

无论您做什么，都建议在 pyproject.toml 中为您的 setuptools 构建要求设置上限，以避免将来出现中断 — 请参阅对于下游包作者。