setup.py最小不可缺字段是name、version、packages;name须合法,version须符合PEP 440,packages推荐用find_packages();其他如install_requires、python_requires为强建议项。

能,但必须用 python -m build 或 python setup.py bdist_wheel,且前提是项目结构和依赖已就绪;直接运行 setup.py 不等于打包成功,它只是入口脚本。
setup.py 文件必须包含哪些最小字段?
缺一不可的只有 name、version、packages。其他如 install_requires、python_requires 是强烈建议项,不是可选装饰:
-
name必须是合法的 Python 包名(仅含字母、数字、下划线,不能以数字开头) -
version应遵循 PEP 440(如"0.1.0",不能写"v0.1"或"0.1-rc") -
packages=find_packages()是最安全的选择;手动写packages=["mylib"]容易漏子包或引入空目录 - 如果项目含非
.py文件(如 JSON、模板),需额外加MANIFEST.in并确保include_package_data=True
为什么推荐用 python -m build 而非 python setup.py bdist_wheel?
python -m build 是当前官方推荐方式(PEP 517/518),它绕过 setup.py 的执行逻辑,只读取声明式配置,更稳定、更隔离:
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
- 不依赖
setup.py是否可 import —— 某些setup.py会动态 import 项目代码,导致构建时触发运行时错误 - 自动启用
pyproject.toml中定义的build-backend(即使你只写了setup.py,build也会 fallback 到 setuptools) - 不会污染当前 Python 环境(
setup.py运行时可能修改sys.path或加载本地模块) - 命令统一:
python -m build --wheel生成.whl,--sdist生成.tar.gz
常见失败现象和对应检查点
运行后没生成 dist/*.whl,或报错信息模糊,多数卡在这几个地方:
- 报错
ModuleNotFoundError: No module named 'setuptools':说明当前环境没装setuptools或版本太老,运行pip install -U setuptools wheel - 报错
error in mypkg setup command: 'install_requires' must be a string or list of strings:检查install_requires值是否为列表,不能是元组或带换行的字符串 - 生成的
.whl安装后找不到模块:确认find_packages()找到的是源码目录(比如src/mylib/需配find_packages(where="src")和package_dir={"": "src"}) - 文件名里出现
py3-none-any.whl但你想支持 C 扩展:这是纯 Python 包标识;含 C 代码必须用setuptools+ 编译器,并在setup.py中显式定义Extension
真正容易被忽略的是:.whl 文件名中的 python tag(如 py39)由构建时 Python 解释器决定,不是 python_requires 控制的;想发多版本包,得在对应 Python 版本环境下分别构建。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










