基于setuptools的pip包安装时显示UNKNOWN-0.0.0问题排查

使用pyproject.toml搭配setuptools构建了首个Python包，wheel格式安装正常，但安装*.tar.gz格式包时，项目名称显示为UNKNOWN、版本为0.0.0，尽管已经在配置中设置了myproject_qohelet和1.1。

tar.gz安装日志 #

> pip3 install myproject_qohelet-1.1.tar.gz
Defaulting to user installation because normal site-packages is not writeable
Processing ./myproject_qohelet-1.1.tar.gz
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
  Installing backend dependencies ... done
  Preparing metadata (pyproject.toml) ... done
Building wheels for collected packages: UNKNOWN
  Building wheel for UNKNOWN (pyproject.toml) ... done
  Created wheel for UNKNOWN: filename=UNKNOWN-0.0.0-py3-none-any.whl size=961 sha256=4e10d08c20a9cd5289d673d0627b53012bd917c1372fe681dd6aaa3f4ab64cb0
  Stored in directory: /home/qohelet/.cache/pip/wheels/a8/0a/3d/225cba37f15f2ed307317d99dac03d622d5126e236877dc072
Successfully built UNKNOWN
Installing collected packages: UNKNOWN
  Attempting uninstall: UNKNOWN
    Found existing installation: UNKNOWN 0.0.0
    Uninstalling UNKNOWN-0.0.0:
      Successfully uninstalled UNKNOWN-0.0.0
Successfully installed UNKNOWN-0.0.0

pyproject.toml配置 #

title = "myProject"

[owner]
name = "Qohelet"

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[project]
name = "myproject_qohelet"
version = "1.1"
authors = [
  { name="Qohelet", email="qohelet@example.com" },
]
license = { text = "GPL" }
description = "This is a project that can be installed with pip"
readme = "README.md"
requires-python = ">=3.7"
classifiers = [
    "Programming Language :: Python :: 3",
    "Operating System :: OS Independent",
]

[project.urls]
"Homepage" = "https://gitlab.com/qohelet/myProject"
"Bug Tracker" = "https://gitlab.com/qohelet/myProject/-/issues"

构建命令 #

python3 -m pip install --upgrade build
python3 -m build

wheel安装日志（正常） #

> pip3 install myproject_qohelet-1.1-py3-none-any.whl --force-reinstall
Defaulting to user installation because normal site-packages is not writeable
Processing ./myproject_qohelet-1.1-py3-none-any.whl
Installing collected packages: myproject-qohelet
  Attempting uninstall: myproject-qohelet
    Found existing installation: myproject_qohelet 1.1
    Uninstalling myproject_qohelet-1.1:
      Successfully uninstalled myproject_qohelet-1.1
Successfully installed myproject-qohelet-1.1

问题根源是你在[build-system]里引入了setuptools-scm，但构建的tar.gz源码包中没有包含Git仓库的元数据（比如.git目录或版本标记文件），导致setuptools-scm无法自动识别版本，进而回退到默认的UNKNOWN-0.0.0。而wheel包在构建时已经把版本信息固化进去了，所以不受影响。

有三种可行的解决方式：

方式一：移除setuptools-scm依赖 #

如果你不需要自动从Git标签生成版本号，直接删掉setuptools-scm即可：
修改pyproject.toml的[build-system]部分：

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

重新构建包后，tar.gz安装时就会读取你手动设置的name和version。

方式二：让setuptools-scm使用手动配置的版本作为 fallback #

在pyproject.toml中添加[tool.setuptools-scm]配置，指定fallback版本：

[tool.setuptools-scm]
fallback_version = "1.1"

这样即使Git元数据缺失，也会使用你设置的版本，同时保留Git自动版本的功能。

方式三：构建源码包时包含版本文件 #

使用setuptools-scm的write_to选项，在构建时自动生成包含版本信息的文件，并打包进tar.gz：

[tool.setuptools-scm]
write_to = "myproject_qohelet/_version.py"

需要确保你的包目录（myproject_qohelet）存在，并且__init__.py可以导入这个版本文件，这样源码包安装时setuptools-scm就能读取到版本信息。

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