如何正确使用setuptools-scm生成符合要求的版本号？

核心思路 #

你要的是基于最新正式标签（比如1.2.3）生成1.2.3.dev1、1.2.3.dev2这类开发版本，而不是自动跳到1.2.4加哈希后缀。关键就是通过配置控制版本生成规则，禁用本地哈希后缀，指定分支的版本逻辑。

具体配置步骤 #

1. 基础配置pyproject.toml #

先确保装了setuptools-scm，然后在项目根目录的pyproject.toml里添加这些内容：

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

[tool.setuptools_scm]
# 允许工具检测当前分支
branch = true
# 去掉PyPI不接受的+gxxx这类本地哈希后缀
local_scheme = "no-local-version"

2. 指定开发版本生成规则 #

加上version_scheme = "guess-next-dev"，这个规则会基于最新的SemVer标签，生成x.y.z.devN格式（N是标签之后的提交次数），不会自动把版本升到1.2.4：

[tool.setuptools_scm]
branch = true
version_scheme = "guess-next-dev"
local_scheme = "no-local-version"

3. 分支专属规则（可选） #

如果只想让develop分支用这个规则，main分支保持正式版本，就添加分支映射：

[tool.setuptools_scm.branch_scheme]
develop = "guess-next-dev"
main = "release-branch-semver"

4. 验证配置 #

在项目根目录运行下面的命令，查看生成的版本是否符合预期：

python -m setuptools_scm

要是输出1.2.3.dev1这类格式，就说明配置生效了。

踩坑排查 #

• 要是还是生成1.2.4，先检查最新的Git标签是不是严格的SemVer格式（比如v1.2.3或者1.2.3都行，但别混着用），还要确保标签已经推到仓库。
• PyPI拒接版本的话，记住+gxxx是本地版本标识，PyPI不接受，所以local_scheme = "no-local-version"必须加；而x.y.z.devN是完全符合PEP 440规范的，没问题。

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