如何用pyproject.toml生成对应特定Python版本的wheel包

核心原因 #

你遇到的差异是因为：在setup.py中，只要项目包含编译后的扩展（或预编译的依赖如dll），setuptools会自动识别为非纯Python包，生成带-cp311-cp311这类ABI/版本标记的轮子；而仅设置requires-python的pyproject.toml默认会被识别为纯Python包，生成-py3-none-any的通用轮子。

具体解决方案 #

1. 配置构建后端与基础设置 #

确保pyproject.toml的[build-system]部分正确指定setuptools和wheel，这是生成ABI特定轮子的基础：

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"

2. 标记包为平台/ABI特定 #

添加setuptools配置，明确告知工具这不是纯Python包，需要生成版本/平台绑定的轮子：

[tool.setuptools]
platform-specific = true

3. 保留Python版本限制 #

继续设置requires-python以限制安装时的Python版本，效果和setup.py的python_requires完全一致：

[project]
name = "your-package-name"
requires-python = "~=3.11"
# 其他项目配置（版本、作者等）

4. 正确包含预编译dll #

如果你的dll是随包分发的预编译文件，需要通过package-data配置让setuptools打包时包含它们：

[tool.setuptools.package-data]
"your_package_name" = ["*.dll"]
# 替换成你的实际包名，若dll在子目录可写如"your_package_name/lib/*.dll"

5. 构建验证 #

执行构建命令：

python -m build

此时生成的wheel包名应该会带有-cp311-cp311-<your-platform>的后缀，同时pip安装时会自动检查Python版本，不符合~=3.11的环境会直接拒绝安装。

额外说明 #

如果你的dll是通过setuptools编译生成的（比如用Cython或C扩展），还需要在pyproject.toml中配置扩展模块，示例：

[tool.setuptools.extensions]
"your_package_name.your_extension" = {sources = ["src/your_extension.c"]}

这种情况下，setuptools会自动编译并生成ABI绑定的轮子，无需额外设置platform-specific（不过设置了也不会冲突）。

内容的提问来源于stack exchange，提问作者arc_lupus