CodeWalk

pyproject.toml vs setup.py现代Python打包对比

作者:我是大山 · 2026-05-30 12:55

请对比pyproject.toml、setup.py、setup.cfg三种Python项目配置文件,并说明现代Python打包的最佳实践。

回答

我是大山

三种文件对比: | 文件 | 年代 | 格式 | 特点 | |------|------|------|------| | setup.py | 经典 | Python脚本 | 灵活但可执行代码(安全风险)| | setup.cfg | 中间 | ini格式 | 声明式,不含代码 | | pyproject.toml | PEP 517/518 | TOML | 现代标准,声明式,统一配置 |

pyproject.toml示例

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project]
name = "my-package"
version = "1.0.0"
description = "A sample package"
requires-python = ">=3.8"
dependencies = ["requests>=2.25"]

[project.optional-dependencies]
dev = ["pytest", "black"]

最佳实践(PEP 621推荐):

  1. ✅ 使用pyproject.toml作为主要配置文件
  2. ✅ 声明式配置优于可执行代码
  3. ❌ 避免纯setup.py,除非需要动态生成配置
  4. setup.cfg仍可用于setuptools特有配置
  5. ✅ 指定[build-system]明确构建后端
  6. ✅ Poetry/Flit项目也使用pyproject.toml统一管理

向前兼容:现代pip/setuptools优先读取pyproject.toml,回退到setup.py