[BUG]: nightly wheels are versioned 3.1.0 = the PyPI release since #6125, so the SPEC 4 install recipe cannot pick them up

[glaziermag]

Required prerequisites

• Make sure you've read the documentation. Your issue may be addressed there.
• Search the issue tracker and Discussions to verify that this hasn't already been reported. +1 or comment there if it has.
• Consider asking first in the Gitter chat room or in a Discussion.

What version (or hash if on master) of pybind11 are you using?

master 296d5d1, as uploaded by nightly run 35680614212 (2026-09-22)

Problem description

Since #6125 set the version of record on master to 3.1.0 final (2026-08-06), the daily nightlies.yml run builds master and uploads it to scientific-python-nightly-wheels as pybind11-3.1.0-py3-none-any.whl, the same version string as the PyPI release (first such upload: run 31144654332, 2026-08-07; the 08-06 run still uploaded 3.1.0a0). Two effects, seen with pip 26.0.1:

1. The SPEC 4 recipe the README badge points at, pip install --pre --upgrade --extra-index-url … pybind11, cannot move an environment that already has 3.1.0 onto the nightly: pip answers Requirement already satisfied: pybind11 (3.1.0).
2. On a fresh environment, or with pybind11==3.1.0 pinned and the nightly index configured, pip picked the anaconda wheel: a master snapshot that reports __version__ == "3.1.0" and PYBIND11_VERSION_HEX == 0x030100F0. Today's upload differs from the PyPI 3.1.0 wheel in 12 header files (detail/internals.h, detail/type_caster_base.h, detail/struct_smart_holder.h, detail/init.h, pybind11.h, numpy.h, …), so a dependent testing against "the nightly" cannot tell which 3.1.0 it built against.

The upload step is green throughout ([WARNING] Distribution "pybind11-3.1.0-py3-none-any.whl" already exists. Removing. … Upload complete), so nothing flags it. After 3.0.0, #5747 bumped master to 3.0.1a0 the next day, which is what keeps a nightly sorting above the release; after 3.0.1 (f5fbe86, 2025-08-22) master stayed at 3.0.1 final until 45fab40 (2026-02-17) with this workflow running daily, so this is the second time. docs/release.rst "Post-release work" (296d5d1, L207-209) allows "no immediate bump", and detail/common.h L24-25 says development versions use the alpha level; the nightly wheelhouse only works under the second.

Reproducible example code

$ python -m venv v && v/bin/pip -q install pybind11==3.1.0
$ v/bin/pip install --pre --upgrade --extra-index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple pybind11
Requirement already satisfied: pybind11 in ./v/lib/python3.14/site-packages (3.1.0)

$ pip download --no-deps --pre --index-url https://pypi.anaconda.org/scientific-python-nightly-wheels/simple pybind11 -d nightly
$ pip download --no-deps pybind11==3.1.0 -d pypi
$ unzip -q nightly/*.whl -d n && unzip -q pypi/*.whl -d p && diff -rq n p | grep -vc dist-info
12

Is this a regression? Put the last known working version here if it is.

Not a regression in pybind11 itself; nightlies last sorted above the release while master was 3.1.0a0 (until run 31069110173, 2026-08-06).

Two ways to close this: bump master to 3.1.1a0 or 3.2.0a0 as #5747 did, or make nightlies.yml skip (or fail) the upload when PYBIND11_VERSION_RELEASE_LEVEL is PY_RELEASE_LEVEL_FINAL, so a nightly can never carry a published version whatever the post-release decision is. I'd take the second, since the bump alone lapsed after 3.0.1.

Found while checking the scientific-python nightly wheelhouse with Claude Code; the commands above were run as shown on 2026-09-22.