maiaimei
pyproject.toml 是现代 Python 项目的“总配置中心”，由 PEP 517/518/621 标准化，用来告诉 pip、poetry、uv 等工具：
“这个项目叫啥、用哪个 Python、依赖谁、怎么构建、黑/测/类型检查工具怎么配”。
替代了过去散落各处的 setup.py + setup.cfg + requirements.txt + pytest.ini + .flake8 那种混乱局面。
它是一个放在项目根目录的 TOML 格式静态文件。
它不是“脚本”，不执行 Python 代码，只是“填表”。
# 一、pyproject.toml 语法去哪查（按“查什么”分层）
pyproject.toml 的语法其实由三层叠出来，查的时候别只盯一个页面：
# 1. TOML 基础语法（最底层）
- 官网：https://toml.io (opens new window)
- 管的是：键值对、表
[x]、数组、注释、a.b.c嵌套怎么写 - TOML 本身对 key/table 的顺序没有任何语义要求
# 2. pyproject.toml 的“标准契约”（Python 官方）
由这些规范定义：
- PEP 518 → 定义
[build-system]和[tool]命名空间 - PEP 621 → 定义
[project]表里的标准字段（name/version/dependencies…） - Python Packaging User Guide 正式规范页： https://packaging.python.org/en/latest/specifications/declaring-project-metadata （中文镜像：https://packaging.pythonlang.cn/en/latest/specifications/pyproject-toml ）
- 用户向写作指南： https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
# 3. 构建后端扩展字段（setuptools / hatch / poetry…）
- setuptools 专属：
[tool.setuptools]→ https://setuptools.pypa.io/en/latest/userguide/pyproject_config.html - hatchling：
[tool.hatch] - poetry：不用
[project]，用[tool.poetry]（Poetry 自己的一套） - uv / pdm / ruff / mypy / pytest 各自查各自文档，都挂在
[tool.xxx]下
✅ 查字段时先问：这字段是 PEP 621 标准、TOML 通用，还是 某个后端/工具私有？
# 二、配置节点有没有顺序要求？
# 结论先给
TOML 层面：完全无序。
pyproject.toml 规范：顶层表顺序随意，表内 key 顺序也随意。
下面这些都等价、合法、构建结果一样：
[tool.ruff]
line-length = 88
[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"
[project]
name = "demo"
version = "0.1.0"
[project]
name = "demo"
version = "0.1.0"
[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"
[tool.ruff]
line-length = 88
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 但有三条“硬边界”要注意
- key 必须待在对的表里
requires只能在[build-system]下dependencies只能在[project]下line-length只能在[tool.ruff]下，不能提到顶层
- 同一个表不能重复定义冲突值（TOML 本身不允许同表同 key 出现两次）
[project]里name必填且不能 dynamic；version必填或声明dynamic = ["version"]（PEP 621 规定）
# 社区约定俗成的顺序（不是语法要求）
虽然无序，但人和工具都爱看这个顺序，建议你笔记里也这么排：
[build-system] # 1. 先告诉构建前端怎么建
[project] # 2. 项目身份证 + 运行依赖
[project.optional-dependencies]
[project.scripts]
[project.urls]
[tool.xxx] # 3. 黑/测/类型/后端扩展放最后
1
2
3
4
5
6
2
3
4
5
6
理由：[build-system] 在 pip install . 最早被读，[project] 是人最关心的，[tool] 是噪音最大的部分。
# 三、一句话写进笔记
pyproject.toml 语法 = TOML 语法 + PEP 518/621 标准表 + 后端/工具私有
[tool.xxx]；所有 table 和 key 顺序均无要求，但 key 必须属于正确的 table；社区习惯按 build-system → project → tool 排。