6.1 pyproject.toml 完整指南

Tue, 20 Jan 2026 00:00:00 +0000

本章介紹 pyproject.toml 的結構與設定方式。

本章目標

學完本章後，你將能夠：

理解 pyproject.toml 的三個主要表
設定專案元數據（PEP 621）
設定建構系統（PEP 518）

【原理層】pyproject.toml 的演進

歷史背景

1Python 打包的演進：
2├── 2000s: setup.py（純 Python 腳本）
3├── 2010s: setup.cfg（宣告式設定）
4├── 2016: PEP 518（pyproject.toml 誕生）
5├── 2020: PEP 621（標準化元數據）
6└── 2025: pyproject.toml 成為主流標準

為什麼需要 pyproject.toml？

 1setup.py 的問題：
 2├── 需要執行程式碼才能讀取元數據
 3├── 安全風險（任意程式碼執行）
 4├── 無法標準化建構依賴
 5└── 不同工具使用不同設定檔
 6
 7pyproject.toml 的優點：
 8├── 靜態設定，不需執行
 9├── 標準化格式（TOML）
10├── 統一的設定位置
11└── 支援多種建構後端

PEP	內容	狀態
PEP 518	build-system 表	已採納
PEP 621	project 元數據	已採納
PEP 639	license 欄位改進	已採納
PEP 660	可編輯安裝	已採納
PEP 735	依賴群組	草案中

【設計層】三個主要表

檔案結構總覽

 1# pyproject.toml 的三個主要表
 2
 3[build-system]
 4# 定義如何建構套件
 5requires = ["setuptools>=61.0"]
 6build-backend = "setuptools.build_meta"
 7
 8[project]
 9# 定義套件的元數據
10name = "my-package"
11version = "1.0.0"
12# ...
13
14[tool.xxx]
15# 各種工具的設定
16# [tool.setuptools], [tool.pytest], [tool.ruff], etc.

[build-system]：建構設定

 1[build-system]
 2# 建構時需要的套件（PEP 518）
 3requires = [
 4 "setuptools>=61.0",
 5 "wheel",
 6 # 如果有 C 擴展
 7 # "cython>=3.0",
 8]
 9
10# 建構後端（PEP 517）
11build-backend = "setuptools.build_meta"
12
13# 選用：後端路徑（較少使用）
14# backend-path = ["."]

常見的建構後端：

1建構後端 requires
2─────────────────────────────────────────────────────
3setuptools.build_meta ["setuptools>=61.0"]
4flit_core.buildapi ["flit_core>=3.4"]
5hatchling.build ["hatchling"]
6poetry.core.masonry.api ["poetry-core>=1.0.0"]
7maturin ["maturin>=1.5"]
8scikit_build_core.build ["scikit-build-core>=0.5"]
9mesonpy ["meson-python"]

[project]：專案元數據

 1[project]
 2# === 必填欄位 ===
 3name = "my-awesome-package"
 4version = "1.0.0"
 5
 6# === 基本資訊 ===
 7description = "A short description of the package"
 8readme = "README.md" # 或 {file = "README.md", content-type = "text/markdown"}
 9license = {text = "MIT"} # 或 {file = "LICENSE"}
10requires-python = ">=3.8"
11
12# === 作者資訊 ===
13authors = [
14 {name = "Your Name", email = "you@example.com"},
15]
16maintainers = [
17 {name = "Maintainer", email = "maintainer@example.com"},
18]
19
20# === 分類與關鍵字 ===
21keywords = ["example", "package", "demo"]
22classifiers = [
23 "Development Status :: 4 - Beta",
24 "Intended Audience :: Developers",
25 "License :: OSI Approved :: MIT License",
26 "Programming Language :: Python :: 3",
27 "Programming Language :: Python :: 3.8",
28 "Programming Language :: Python :: 3.9",
29 "Programming Language :: Python :: 3.10",
30 "Programming Language :: Python :: 3.11",
31 "Programming Language :: Python :: 3.12",
32]
33
34# === URL ===
35[project.urls]
36Homepage = "https://github.com/user/project"
37Documentation = "https://project.readthedocs.io"
38Repository = "https://github.com/user/project"
39Changelog = "https://github.com/user/project/blob/main/CHANGELOG.md"
40
41# === 依賴 ===
42dependencies = [
43 "requests>=2.28",
44 "click>=8.0",
45]
46
47[project.optional-dependencies]
48dev = [
49 "pytest>=7.0",
50 "pytest-cov",
51 "ruff",
52 "mypy",
53]
54docs = [
55 "sphinx>=6.0",
56 "sphinx-rtd-theme",
57]
58
59# === 入口點 ===
60[project.scripts]
61my-cli = "my_package.cli:main"
62
63[project.gui-scripts]
64my-gui = "my_package.gui:main"
65
66[project.entry-points."my_package.plugins"]
67plugin1 = "my_package.plugins.plugin1:Plugin"

[tool.xxx]：工具設定

 1# === setuptools 設定 ===
 2[tool.setuptools]
 3packages = ["my_package"]
 4# 或使用自動發現
 5package-dir = {"" = "src"}
 6
 7[tool.setuptools.packages.find]
 8where = ["src"]
 9
10[tool.setuptools.package-data]
11my_package = ["*.json", "data/*"]
12
13# === pytest 設定 ===
14[tool.pytest.ini_options]
15testpaths = ["tests"]
16python_files = ["test_*.py"]
17addopts = "-v --cov=my_package"
18
19# === ruff 設定 ===
20[tool.ruff]
21line-length = 88
22target-version = "py38"
23
24[tool.ruff.lint]
25select = ["E", "F", "W", "I", "UP"]
26ignore = ["E501"]
27
28# === mypy 設定 ===
29[tool.mypy]
30python_version = "3.8"
31strict = true
32warn_return_any = true
33
34# === coverage 設定 ===
35[tool.coverage.run]
36source = ["my_package"]
37branch = true
38
39[tool.coverage.report]
40exclude_lines = [
41 "pragma: no cover",
42 "if TYPE_CHECKING:",
43]

【實作層】完整範例

最小可行設定

1# 最小的 pyproject.toml
2[build-system]
3requires = ["setuptools>=61.0"]
4build-backend = "setuptools.build_meta"
5
6[project]
7name = "my-package"
8version = "0.1.0"

標準函式庫風格

 1[build-system]
 2requires = ["setuptools>=61.0"]
 3build-backend = "setuptools.build_meta"
 4
 5[project]
 6name = "my-package"
 7version = "1.0.0"
 8description = "A well-documented Python package"
 9readme = "README.md"
10license = {text = "MIT"}
11requires-python = ">=3.8"
12authors = [{name = "Your Name", email = "you@example.com"}]
13classifiers = [
14 "Development Status :: 4 - Beta",
15 "Intended Audience :: Developers",
16 "License :: OSI Approved :: MIT License",
17 "Operating System :: OS Independent",
18 "Programming Language :: Python :: 3",
19 "Programming Language :: Python :: 3.8",
20 "Programming Language :: Python :: 3.9",
21 "Programming Language :: Python :: 3.10",
22 "Programming Language :: Python :: 3.11",
23 "Programming Language :: Python :: 3.12",
24 "Typing :: Typed",
25]
26dependencies = []
27
28[project.optional-dependencies]
29dev = ["pytest>=7.0", "ruff", "mypy"]
30
31[project.urls]
32Homepage = "https://github.com/user/my-package"
33Repository = "https://github.com/user/my-package"
34
35[tool.setuptools.packages.find]
36where = ["src"]

含 CLI 的應用程式

 1[build-system]
 2requires = ["setuptools>=61.0"]
 3build-backend = "setuptools.build_meta"
 4
 5[project]
 6name = "my-cli-tool"
 7version = "2.0.0"
 8description = "A powerful CLI tool"
 9readme = "README.md"
10license = {text = "Apache-2.0"}
11requires-python = ">=3.9"
12authors = [{name = "CLI Team"}]
13dependencies = [
14 "click>=8.0",
15 "rich>=13.0",
16]
17
18[project.optional-dependencies]
19dev = ["pytest", "pytest-cov"]
20
21[project.scripts]
22my-tool = "my_cli_tool.main:cli"
23
24[project.urls]
25Homepage = "https://my-cli-tool.dev"
26
27[tool.setuptools.packages.find]
28where = ["src"]
29
30[tool.setuptools.package-data]
31my_cli_tool = ["templates/*.txt", "config/*.yaml"]

【進階】動態欄位

動態版本

1[project]
2name = "my-package"
3dynamic = ["version"] # 版本由其他來源決定
4
5[tool.setuptools.dynamic]
6version = {attr = "my_package.__version__"}
7# 或從檔案讀取
8# version = {file = "VERSION"}

1# src/my_package/__init__.py
2__version__ = "1.2.3"

動態依賴

1[project]
2name = "my-package"
3dynamic = ["dependencies", "optional-dependencies"]
4
5[tool.setuptools.dynamic]
6dependencies = {file = ["requirements.txt"]}
7optional-dependencies.dev = {file = ["requirements-dev.txt"]}

使用 setuptools-scm（Git 標籤版本）

 1[build-system]
 2requires = ["setuptools>=61.0", "setuptools-scm>=8.0"]
 3build-backend = "setuptools.build_meta"
 4
 5[project]
 6name = "my-package"
 7dynamic = ["version"]
 8
 9[tool.setuptools_scm]
10# 版本從 git tag 自動產生
11# v1.0.0 -> 1.0.0
12# v1.0.0-2-gabcdef -> 1.0.0.dev2+gabcdef

【實作層】專案結構對應

Flat Layout

1my-package/
2├── pyproject.toml
3├── README.md
4├── my_package/
5│ ├── __init__.py
6│ └── module.py
7└── tests/
8 └── test_module.py

1[tool.setuptools]
2packages = ["my_package"]

Src Layout（推薦）

1my-package/
2├── pyproject.toml
3├── README.md
4├── src/
5│ └── my_package/
6│ ├── __init__.py
7│ └── module.py
8└── tests/
9 └── test_module.py

1[tool.setuptools.packages.find]
2where = ["src"]

為什麼推薦 src layout？

1Src Layout 的優點：
2├── 避免匯入本地未安裝的套件
3├── 強制測試已安裝的版本
4├── 清楚區分原始碼和專案根目錄
5└── 避免名稱衝突

【進階】PEP 639 授權條款

新的 license 語法

 1# PEP 639（Python 3.14+，但建構工具已支援）
 2
 3# SPDX 表示法
 4[project]
 5license = "MIT"
 6# 或
 7license = "Apache-2.0 OR MIT"
 8# 或
 9license = "GPL-3.0-only"
10
11# 授權檔案
12license-files = ["LICENSE", "LICENSES/*"]

常見的 SPDX 識別碼

 1識別碼 完整名稱
 2─────────────────────────────────────────
 3MIT MIT License
 4Apache-2.0 Apache License 2.0
 5GPL-3.0-only GNU GPL v3.0 only
 6GPL-3.0-or-later GNU GPL v3.0 or later
 7BSD-3-Clause BSD 3-Clause License
 8BSD-2-Clause BSD 2-Clause License
 9MPL-2.0 Mozilla Public License 2.0
10LGPL-3.0-only GNU LGPL v3.0 only
11ISC ISC License
12Unlicense The Unlicense

【驗證】檢查設定

使用 validate-pyproject

1pip install validate-pyproject
2
3# 驗證 pyproject.toml
4validate-pyproject pyproject.toml

使用 build 測試建構

1pip install build
2
3# 建構套件（會驗證設定）
4python -m build
5
6# 建構結果
7ls dist/
8# my_package-1.0.0.tar.gz
9# my_package-1.0.0-py3-none-any.whl

常見錯誤

 1錯誤：Unknown key in [project]
 2原因：使用了非標準欄位
 3解決：檢查 PEP 621 允許的欄位
 4
 5錯誤：Invalid version
 6原因：版本格式不符合 PEP 440
 7解決：使用正確格式，如 "1.0.0", "1.0.0a1", "1.0.0.dev1"
 8
 9錯誤：Missing required key
10原因：缺少必填欄位
11解決：至少要有 name 和 version（或 dynamic）

思考題

為什麼 Python 社群花了這麼長時間才標準化打包設定？
[build-system] 中的 requires 和 [project] 中的 dependencies 有什麼區別？
動態欄位在什麼情況下有用？有什麼潛在問題？

實作練習

將一個使用 setup.py 的舊專案遷移到 pyproject.toml
建立一個包含 CLI 入口點的套件，並在本地測試安裝
使用 setuptools-scm 設定自動版本管理

延伸閱讀

下一章：建構系統比較

模組七：打包與發布

Tue, 20 Jan 2026 00:00:00 +0000

本模組介紹現代 Python 套件的打包標準與發布流程。

為什麼學習打包與發布？

完整生命週期：從開發到發布的完整流程
現代標準：pyproject.toml 與 PEP 標準
工具比較：setuptools、Poetry、Hatch 的選擇

章節列表

章節	主題	關鍵收穫
7.1	pyproject.toml 完整指南	現代設定標準
7.2	建構系統比較	setuptools vs Poetry vs Hatch
7.3	發布到 PyPI	建構與上傳流程
7.4	最佳實踐	套件維護指南
7.5	封裝預編譯二進位	Python 封裝 Go/Rust/C 二進位

先備知識

基本的 Python 開發經驗
了解 pip 和虛擬環境

學習時間

每章節約 30-45 分鐘，全模組約 2-3 小時

上一模組：模組六：用 Rust 擴展 Python

Pyproject on Tarragon

6.1 pyproject.toml 完整指南

本章目標

【原理層】pyproject.toml 的演進

歷史背景

為什麼需要 pyproject.toml？

相關 PEP

【設計層】三個主要表

檔案結構總覽

[build-system]：建構設定

[project]：專案元數據

[tool.xxx]：工具設定

【實作層】完整範例

最小可行設定

標準函式庫風格

含 CLI 的應用程式

【進階】動態欄位

動態版本

動態依賴

使用 setuptools-scm（Git 標籤版本）

【實作層】專案結構對應

Flat Layout

Src Layout（推薦）

為什麼推薦 src layout？

【進階】PEP 639 授權條款

新的 license 語法

常見的 SPDX 識別碼

【驗證】檢查設定

使用 validate-pyproject

使用 build 測試建構

常見錯誤

思考題

實作練習

延伸閱讀

模組七：打包與發布

為什麼學習打包與發布？

章節列表

相關 PEP 標準

先備知識

學習時間