如何正确配置pyproject.toml中的tool.setuptools_scm实现动态版本？

问题背景 #

测试pyproject.toml构建示例时，删除[tool.setuptools_scm]行能正常构建，但添加该行后执行命令cd /test/example && python -m build --no-isolation失败，报错显示setuptools-scm无法检测项目版本。

当前pyproject.toml配置 #

[project]
name = "example"

dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "example.__version__"}

[tool.setuptools_scm]

报错信息 #

* Getting build dependencies for sdist...
Traceback (most recent call last):
  File "/usr/local/lib/python3.10/dist-packages/pyproject_hooks/_in_process/_in_process.py", line 353, in <module>
    main()
  File "/usr/local/lib/python3.10/dist-packages/pyproject_hooks/_in_process/_in_process.py", line 335, in main
    json_out['return_val'] = hook(**hook_input['kwargs'])
  File "/usr/local/lib/python3.10/dist-packages/pyproject_hooks/_in_process/_in_process.py", line 287, in get_requires_for_build_sdist
    return hook(config_settings)
  File "/usr/local/lib/python3.10/dist-packages/setuptools/build_meta.py", line 328, in get_requires_for_build_sdist
    return self._get_build_requires(config_settings, requirements=[])
  File "/usr/local/lib/python3.10/dist-packages/setuptools/build_meta.py", line 295, in _get_build_requires
    self.run_setup()
  File "/usr/local/lib/python3.10/dist-packages/setuptools/build_meta.py", line 311, in run_setup
    exec(code, locals())
  File "<string>", line 1, in <module>
  File "/usr/local/lib/python3.10/dist-packages/setuptools/__init__.py", line 103, in setup
    return distutils.core.setup(**attrs)
  File "/usr/local/lib/python3.10/dist-packages/setuptools/_distutils/core.py", line 147, in setup
    _setup_distribution = dist = klass(attrs)
  File "/usr/local/lib/python3.10/dist-packages/setuptools/dist.py", line 303, in __init__
    _Distribution.__init__(self, dist_attrs)
  File "/usr/local/lib/python3.10/dist-packages/setuptools/_distutils/dist.py", line 283, in __init__
    self.finalize_options()
  File "/usr/local/lib/python3.10/dist-packages/setuptools/dist.py", line 654, in finalize_options
    ep(self)
  File "/usr/local/lib/python3.10/dist-packages/setuptools_scm/_integration/setuptools.py", line 121, in infer_version
    _assign_version(dist, config)
  File "/usr/local/lib/python3.10/dist-packages/setuptools_scm/_integration/setuptools.py", line 56, in _assign_version
    _version_missing(config)
  File "/usr/local/lib/python3.10/dist-packages/setuptools_scm/_get_version_impl.py", line 112, in _version_missing
    raise LookupError(
LookupError: setuptools-scm was unable to detect version for /test/example.

Make sure you're either building from a fully intact git repository or PyPI tarballs. Most other sources (such as GitHub's tarballs, a git checkout without the .git folder) don't contain the necessary metadata and will not work.

For example, if you're using pip, instead of https://github.com/user/proj/archive/master.zip use git+https://github.com/user/proj.git#egg=proj

ERROR Backend subprocess exited when trying to invoke get_requires_for_build_sdist

解决方案 #

根据你的需求，分两种场景处理：

场景1：用setuptools-scm自动从Git标签生成版本 #

如果想让setuptools-scm接管版本管理，从Git仓库标签自动推导版本，需要移除手动指定的动态version配置：

修正后的pyproject.toml：

[project]
name = "example"
dynamic = ["version"]

[tool.setuptools_scm]
# 可选配置（按需添加）：
# root = "."                  # 指定版本检测的根目录
# version_scheme = "guess-next-dev"  # 版本号生成规则
# local_scheme = "dirty-tag"          # 本地修改时的版本后缀规则

同时需满足：

• 项目目录是完整的Git仓库（存在.git文件夹）
• 已创建Git标签（执行git tag v0.1.0这类命令打标签）
• 确保安装了setuptools-scm（构建时会自动拉取，本地开发可提前执行pip install setuptools-scm）

场景2：保留手动维护example.__version__，禁用setuptools-scm版本检测 #

如果要保留手动在example.__version__中维护版本，同时保留[tool.setuptools_scm]区块（比如使用它的其他功能），需要明确指定版本文件路径：

[project]
name = "example"
dynamic = ["version"]

[tool.setuptools.dynamic]
version = {attr = "example.__version__"}

[tool.setuptools_scm]
# 指定版本文件路径，让setuptools-scm读取该文件的版本
version_file = "example/__init__.py"

如果不需要setuptools-scm的任何功能，直接删除[tool.setuptools_scm]区块即可（这也是你之前构建成功的状态）。

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