pyproject.toml与setuptools.setup()的setup_requires参数有何区别？

核心区别 #

二者的生效阶段、读取主体、稳定性完全不同，是不同时代的Python包构建机制产物：

1. pyproject.toml [build-system] 段依赖（PEP 518定义）

• 生效时机：包构建的最早期阶段，早于任何setup.py/setup.cfg脚本的运行
• 读取主体：pip、python-build等构建前端工具，不是setuptools本身
• 作用：明确告知构建前端，启动整个包构建流程前需要预装的基础依赖，常见的包括setuptools、wheel、cython、setuptools-scm等构建过程必需的工具。

2. setuptools.setup() 的 setup_requires 参数

• 生效时机：setuptools已经启动、正在执行setup()脚本的阶段才会处理
• 读取主体：setuptools本身，不会被外部构建前端识别
• 局限：是setuptools早期的私有权衡方案，处理依赖时不会走pip的依赖解析逻辑，会自行从PyPI拉包安装，容易出现依赖冲突、安装失败的问题，且安装的依赖仅临时作用于setup运行环境，不会写入用户的全局/虚拟环境依赖记录。

实际使用场景对比 #

举个包含Cython代码的包构建场景：

如果你把cython写在setup_requires里：pip启动构建时不知道要预装cython，等setuptools运行setup脚本时才会自行拉取cython安装，这个过程很容易和本地已有的cython版本冲突，或因网络问题拉取失败后无完善的重试/报错机制。
如果你把cython写在pyproject.toml的build-system.requires里：pip在启动任何构建步骤前，就会按照标准依赖解析逻辑装好所有指定的构建依赖，再执行后续的setup流程，稳定性和兼容性都有保障。

现状 #

setup_requires已经被官方标记为弃用，现在所有构建相关的依赖都应该统一放到pyproject.toml的[build-system]段中声明，不需要再使用setup_requires。

内容的提问来源于stack exchange，提问作者cowlinator