setup.cfg已被pyproject.toml取代，因其不支持动态逻辑、环境标记和现代构建后端声明，且Python 3.13移除distutils后其底层支撑消失，仅作为静态兼容层存在。

setup.cfg 已被官方弃用，Python 3.12+ 中 setuptools 默认不再读取它；现在应优先用 pyproject.toml，但若维护旧项目或需兼容特定工具链，仍可能遇到它——关键不是“怎么写”，而是“写什么、不写什么、为什么容易失效”。

setup.cfg 的生效前提：必须搭配 setup.py 或 setuptools 40.8.0+

仅放一个 setup.cfg 文件不会自动构建包。常见错误是删掉 setup.py 后发现 pip install . 报错 ModuleNotFoundError: No module named 'setuptools' 或静默忽略配置。

• 必须保留最小化 setup.py：仅含 from setuptools import setup; setup()
• setuptools 版本低于 40.8.0 时，setup.cfg 中的某些字段（如 [options.packages.find]）会被忽略
• 若项目根目录存在 pyproject.toml，即使内容为空，setup.cfg 也会被完全跳过

核心 section 和易错字段：[metadata] 与 [options] 的边界

[metadata] 只管包元信息（名称、版本、作者等），而实际行为控制（包发现、依赖、入口点）全在 [options] 及其子 section。混淆这两者会导致配置不生效。

A Python CLI skill for Cutout.Pro visual APIs — background removal, face cutout, and photo enhancement. Supports file upload & image URL input.

调用 Cutout.Pro 视觉处理 API 进行背景移除、人像抠图和照片增强，支持文件上传与图片 URL 输入。

下载

• version 必须写死或用 attr: 引用模块属性（如 version = attr: mypkg.__version__），不能写 version = 0.1.0.dev0+git 这类动态字符串
• packages 若设为 find:，必须同时声明 [options.packages.find]，且 where 路径需相对于 setup.cfg 所在目录（默认是 .）
• install_requires 中的版本约束写法要严格：用 >=3.8，别用 >= 3.8（空格会解析失败）
• entry_points 必须缩进对齐，且键名只能是标准组名（如 console_scripts），拼错如 consoe_scripts 将静默失效

替代 setup.cfg 的现代写法：pyproject.toml 中对应字段映射

很多团队误以为 “迁移到 pyproject.toml 就是把 setup.cfg 按行翻译过去”，结果因格式差异导致构建失败。关键区别在于 TOML 是分层结构，而 cfg 是扁平 key-value。

立即学习“Python免费学习笔记（深入）”；

• [metadata] → [project]（注意：classifiers 变成 classifiers = ["Programming Language :: Python :: 3"]）
• [options] → [project.optional-dependencies] 或 [project.urls]，而非全塞进 [project]
• [options.packages.find] → [tool.setuptools.packages.find]（注意命名空间前缀 tool.setuptools）
• python_requires 在 [options] 里是顶层字段，在 [project] 里是 requires-python = ">=3.8"

真正麻烦的不是语法转换，而是 setup.cfg 隐式依赖 setuptools 的默认行为（比如自动包含 tests/ 目录），而 pyproject.toml 要求显式声明所有行为——这点在 CI 环境中特别容易暴露。