setup.cfg 已被弃用，新项目应使用 pyproject.toml；其最小配置含 [build-system] 和 [project] 两段，支持动态版本、现代构建后端，并可通过 hatch 快速生成。

setup.cfg 已被弃用，别再手动写它了

Python 官方从 setuptools 61.0.0（2022 年中）起正式标记 setup.cfg 为 deprecated，现在新建项目不应再以它为首选配置方式。它不支持动态元数据（如从 pyproject.toml 读取版本）、无法与现代构建后端（如 build、pip 22.3+）协同工作，且容易因语法缩进/节名拼写错误导致安装失败却无明确提示。

用 pyproject.toml 替代 setup.cfg 的最小可行配置

所有新项目应直接使用 pyproject.toml，它统一声明构建系统、依赖、入口点等。最简可用配置只需两段：

[build-system]
requires = ["setuptools>=45", "wheel", "setuptools_scm[toml]>=6.2"]
build-backend = "setuptools.build_meta"

[project]
name = "mylib"
version = "0.1.0"
description = "A sample package"
authors = [{name = "You", email = "you@example.com"}]
requires-python = ">=3.8"
dependencies = [
    "requests>=2.25.0",
    "click>=8.0",
]

注意：setuptools_scm 可自动从 Git 标签推导版本，避免硬编码；若不用 Git，把 version 改成字符串即可。

旧项目迁移时 setup.cfg 到 pyproject.toml 的对应关系

常见 setup.cfg 节在 pyproject.toml 中的映射不是 1:1，尤其要注意以下几点：

macOS UI 自动化技能包 —— 用 Python 控制你的 Mac

让 macOS 自动化像说话一样简单 —— 用代码控制你的 Mac，无需学习 AppleScript 系统要求 macOS 14+ (Sonoma) Python 3.9+ 需要开启：辅助功能 + 屏幕录制权限

下载

• [metadata] → [project]，但 long_description 需改用 readme = "README.md" 或内联字符串
• [options] → [project] 中的 dependencies 和 requires-python，不再有 install_requires 字段
• [options.packages.find] → [project] 下加 dynamic = ["version"] 或显式写 packages = ["mylib"]；默认不自动发现包
• [options.entry_points] → [project.entry-points."console_scripts"]，键名必须带引号，值为 "cmd = mylib.cli:main" 形式

生成工具推荐：只用 hatch new，别碰 cookiecutter

想“快速生成”配置？直接运行：

pipx install hatch
hatch new myproject

它会创建含 pyproject.toml、src/ 结构、测试骨架和预设 CI 配置的项目。比手动填 setup.cfg 更可靠，也比老旧的 cookiecutter-pypackage 更贴合当前 PEP 517/518 规范。如果已有代码但缺配置，用 hatch init 在当前目录补全即可。

真正容易被忽略的是：哪怕只是本地开发，也要确保 pip install -e . 能成功——这会触发 pyproject.toml 解析，暴露字段名大小写、缩进层级、依赖格式等隐形问题。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！