当使用 pyproject.toml 构建 python 包时，若 pip install 源码分发包（.tar.gz）仍显示项目名为 unknown、版本为 0.0.0，通常是因 pip 版本过旧，无法正确解析现代 pep 621 元数据所致。升级 pip 即可解决。
当使用 pyproject.toml 构建 python 包时，若 pip install 源码分发包（.tar.gz）仍显示项目名为 unknown、版本为 0.0.0，通常是因 pip 版本过旧，无法正确解析现代 pep 621 元数据所致。升级 pip 即可解决。
在现代 Python 打包实践中，pyproject.toml 已完全取代 setup.py 和 setup.cfg，成为标准配置文件。你的 pyproject.toml 结构符合 PEP 621 规范：[project] 表中明确定义了 name = "myproject_qohelet" 和 version = "1.1"，且构建流程（python -m build）本身完全正确——这从生成的 wheel 文件名 myproject_qohelet-1.1-py3-none-any.whl 可得到验证。
问题根源在于：pip install 源码包（.tar.gz）时，会触发“就地构建”（in-tree build）流程，即 pip 自行调用构建后端提取元数据。该流程对 pyproject.toml 的支持依赖于 pip 内置的构建逻辑成熟度。
早期 pip 版本（如 22.0.2 及更早）虽支持 pyproject.toml，但在仅存在 pyproject.toml 而无传统 setup.py 的情况下，其元数据提取逻辑存在缺陷，导致 fallback 到默认值 UNKNOWN 和 0.0.0。而 wheel 文件因已预构建并嵌入完整元数据，故安装时显示正常（如 Successfully installed myproject-qohelet-1.1）。
✅ 解决方案：升级 pip 至 23.1 或更高版本（推荐 ≥24.0）
执行以下命令：
python -m pip install --upgrade "pip>=24.0"
升级后重新安装源码包，即可看到正确名称与版本：
$ pip install myproject_qohelet-1.1.tar.gz ... Building wheels for collected packages: myproject_qohelet Building wheel for myproject_qohelet (pyproject.toml) ... done Created wheel for myproject_qohelet: filename=myproject_qohelet-1.1-py3-none-any.whl Installing collected packages: myproject_qohelet Successfully installed myproject_qohelet-1.1
⚠️ 注意事项：
- 不要回退到 setup.py —— 这违背现代打包最佳实践，且可能引入兼容性问题；
- 确保 CI/CD 环境和团队开发机同步升级 pip，避免构建不一致；
- 若使用 setuptools-scm 动态版本管理，需额外验证 pyproject.toml 中 [tool.setuptools-scm] 配置是否就绪（但本例为静态版本，无需此步骤）；
- 可通过 pip debug --verbose 查看当前 pip 对构建系统的支持能力摘要。
总结：UNKNOWN-0.0.0 是一个典型的“旧工具链不兼容新标准”的提示信号。它并非你的配置错误，而是工具链演进过程中的过渡现象。保持 pip、build、setuptools 等核心工具更新，是保障现代 Python 包可复现、可安装、可维护的关键前提。
