`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 擴充功能，並且僅少量使用 numpy.distutils 功能（超出巢狀 setup.py 檔案之外的功能，這是它最受歡迎的功能，請參閱 Configuration），則最新的 setuptools 可能會繼續正常運作。如果發生問題，您也可以嘗試使用 SETUPTOOLS_USE_DISTUTILS=stdlib 來避免 setuptools 中向後不相容的變更。

無論您執行什麼操作，都建議在您的 pyproject.toml 中為 setuptools 建置需求設定上限，以避免未來發生錯誤 - 請參閱針對下游套件作者。

numpy.distutils 的狀態與遷移建議#