Python项目快速生成setup.cfg方法

Python官方已正式弃用setup.cfg，新项目必须转向更现代、更可靠的pyproject.toml配置方式——它统一管理构建系统、项目元数据和依赖，支持动态版本（如通过setuptools_scm从Git自动推导）、兼容PEP 517/518标准，并能避免setup.cfg常见的缩进错误、字段拼写失误及安装静默失败等问题；只需两段最简配置即可启动项目，而推荐工具hatch new能一键生成符合规范的完整项目骨架，让开发者告别过时的手动配置，真正实现高效、健壮、面向未来的Python包开发。

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，尤其要注意以下几点：

• [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项目快速生成setup.cfg方法》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！