Loading rules_python should not depend on known python versions

[mdorner]

🐞 bug report

Affected Rule

The issue is caused by the rule:

python = use_extension("@rules_python//python/extensions:python.bzl", "python")

Loading python seems to check the system python version. This makes it impossible to use rules_python if the version is not in its version dict:

        File "$BUILD/external/rules_python+/python/private/python_register_toolchains.bzl", line 106, column 31, in python_register_toolchains
                sha256 = tool_versions[python_version]["sha256"].get(platform, None)
Error: key "3.14.0b2" not found in dictionary
ERROR: Analysis of target '@@rules_python+//python/bin:repl' failed; build aborted: 
  error evaluating module extension @@rules_python+//python/extensions:python.bzl%python

Note that this happens when loading the python extension, which is required to configure the python version, creating a catch 22.

Is this a regression?

I have found other occurrences (1,2) of the error message (as below) but I don't think it was traced to this before. It it likely a regression that happens every now and then when some python version gets a weird id and due to the hard coded map of versions in rules_python.

Description

Nothing that depends on rules_python builds. Simplest example
bazel run @rules_python//python/bin:repl

🔬 Minimal Reproduction

This depends on your system python, so it may be best to reproduce in a container. I am running Manjaro with python up to date. The exact python version is 3.14.2 (main, Jan 2 2026, 14:27:39) [GCC 15.2.1 20251112].

Relevant package information (from pacman -Qi python):

Name            : python
Version         : 3.14.2-2
Architecture    : x86_64
Build Date      : Fri 02 Jan 2026 03:27:39 PM CET
Install Date    : Wed 11 Feb 2026 10:13:47 PM CET

Here's my entire python MODULE.bazel setup section (tried older versions of rules_python as well):

bazel_dep(name = "rules_python", version = "1.9.0-rc0")

python = use_extension("@rules_python//python/extensions:python.bzl", "python")
python.toolchain(
    python_version = "3.13",
)
use_repo(python, "python_toolchains")
register_toolchains("@python_toolchains//:all")

🔥 Exception or Error

$ bazel run @rules_python//python/bin:repl 
Starting local Bazel server (8.5.1) and connecting to it...
ERROR: $BUILD/external/rules_python+/python/private/python_register_toolchains.bzl:106:31: Traceback (most recent call last):
        File "$BUILD/external/rules_python+/python/private/python.bzl", line 273, column 53, in _python_impl
                register_result = python_register_toolchains(
        File "$BUILD/external/rules_python+/python/private/python_register_toolchains.bzl", line 106, column 31, in python_register_toolchains
                sha256 = tool_versions[python_version]["sha256"].get(platform, None)
Error: key "3.14.0b2" not found in dictionary
ERROR: Analysis of target '@@rules_python+//python/bin:repl' failed; build aborted: error evaluating module extension @@rules_python+//python/extensions:python.bzl%python

The expectation would be that the unknown python version is ignored as long as a valid python version is configured via python.toolchain(version=$KNOWN_VERSION}). Whatever else depends on the system python version before is quite likely an isolation failure wrt. reproducibility.

🌍 Your Environment

Operating System:
Linux $HOSTNAME 6.18.8-1-MANJARO #1 SMP PREEMPT_DYNAMIC Fri, 30 Jan 2026 23:06:21 +0000 x86_64 GNU/Linux

Output of bazel version:
bazel 8.5.1

Confirmed on 9.0.0 as well

Rules_python version:
1.9.0-rc0, 1.84.0

Anything else relevant?

[rickeylev]

This depends on your system python

Just to verify: you're saying that, if you change what your system python is, this error goes away? That's very strange. The error is occuring during bzlmod phase, but nothing in bzlmod phase looks at the system python.

That "b2" is part of the version is also strange. We had b2 in the list of preconfigured versions briefly, but it's no longer there.

My best guess is that something in the transitive closure of modules is doing e.g. python.toolchain(python_version="3.14.0b2")

Yeah, this shouldn't cause an error. We ran into similar when trying to remove old Python versions

[mdorner]

I've started to debug it, but didn't have time to finish today. The path is:
python/private/python.bzl calls register_toolchains as part of the actual implementation (_python_impl) and cannot live with it if it does not find the toolchain it guessed from the system python version. The "natural" fix of returning None if the requested python version is not supported doesn't seem to do it. In case you want to try:

diff --git a/python/private/python.bzl b/python/private/python.bzl
index 5eb24830..321e44c5 100644
--- a/python/private/python.bzl
+++ b/python/private/python.bzl
@@ -275,7 +275,7 @@ def _python_impl(module_ctx):
             _internal_bzlmod_toolchain_call = True,
             **kwargs
         )
-        if not register_result.impl_repos:
+        if not register_result or not register_result.impl_repos:
             continue
 
         host_platforms = {}
diff --git a/python/private/python_register_toolchains.bzl b/python/private/python_register_toolchains.bzl
index 9e75c419..1acff205 100644
--- a/python/private/python_register_toolchains.bzl
+++ b/python/private/python_register_toolchains.bzl
@@ -103,6 +103,8 @@ def python_register_toolchains(
     # dict[str repo name, tuple[str, platform_info]]
     impl_repos = {}
     for platform, platform_info in platforms.items():
+        if python_version not in tool_versions:
+            return None
         sha256 = tool_versions[python_version]["sha256"].get(platform, None)
         if not sha256:
             continue

I'm not sure what the expectations for that initial call are, but my best guess is that when we determine the system python version we should check that it is supported and otherwise fallback to whatever else is supported or error out clean.

If there's no sane fallback it would probably help to allow configuring this. I would assume that most people will have per project python versions these days (using uv).

[rickeylev]

To clarify: that code doesn't inspect the local system for its Python version. It's only interested in the python.toolchain() calls and their relationship to the "TOOLS" object (a dict of python versions, their urls, shas, etc). This "TOOLS" object is constructed from files like python/versions.bzl and python.single_version_override() et al tag classes.

[mdorner]

Fix: rules_python 1.6.0 removed the "3.14.0b2" python version introduced as preview in 1.5.0. This makes 1.5.0 -> 1.6.0 a breaking change if you have deps that use it. Either pin rules_python to the version your dep uses or use a different version. grpc has this problem in 1.78.0 (1.76.0 works, so does HEAD@master). You can identify the culprit by searching the cache directory for the - fortunately very specific - "3.14.0b2" string.

So, you're right and now that I had some time to dig in, it's much worse than I thought. It's a really weird cross module backward breaking change that is unfortunately not isolated to my setup at all. First of all what's immediately not working:

grpc 1.78.0 includes a MODULE.bazel with this:

bazel_dep(name = "rules_python", version = "1.5.4")

PYTHON_VERSIONS = [
    "3.9",
    "3.10",
    "3.11",
    "3.12",
    "3.13",
    "3.14.0b2",
]

I appears that in the 1.5.0 release support for 3.14.0b2 was added but later removed. This broke grpc and various thing that depend on it transitively (see original issue desc). So it would probably be smart to add that version back somehow and cherrypick the fix into the various versions. Also the tools file should probably mention that it's not safe to remove a version (ever?).

How did I arrive at this conclusion? I found this via rg "3.14.0b2"-ing my cache after noticing that I'm on python 3.14.2 and this is python 3.14.0-b2 (i.e., not my python version). A varity of other things also still had that version somewhere tugged away, but grpc came back after I deleted the cache.

That python version not existing should probably still not break the world and at least load the extension so people can configure which python toolchain to use. I'd assume that grpc would work fine here if at least one of the other versions would be configured. A better error message may also lead to less confusion down the road. Sorry for any that I have caused.

[aignas]

#3387 should have fixed this for pip.parse and python.toolchain calls. It would be great to have an analysis for this to know the root cause.

[rickeylev]

For reference, 3387 / 846dfd0 is in version 1.8 and higher.

3.14.0b2 was added in 9b8f650 (v1.5)
3.14.0b2 was removed, replaced with 3.14.0b3 in 29a7f6a (v1.6)
(b3 then went through a0 etc over the next month or two)

i.e. is was around for about a month.

patching older versions

Looking at 3387, the diff is rather large. No idea if it'll cleanly apply to 1.5, 1.6, and 1.7. A simpler fix (e.g. check for key existing else skip) might be easier, or might just introduce a subtle other problem. Or, maybe just add 3.14.0b2 back into the versions.bzl for 1.5-1.7.

I'm thinking patching versions.bzl is probably the better option. I'm happy to approve a PR to those release branches.

[aignas]

I noticed, that backport for 1.5 and 1.6 would involve also backporting the hub_builder itself, so that might be a noticable effort. Since, the integration of hub_builder is somewhat straightward, we could just copy the implementation from 846dfd0 and copy the integration in extension.bzl file as well. Should be reasonable.

At least on the 1.5 the git cherry-pick failed because of the hub_builder and the python_versions.bzl changes. The python_versions.bzl should not be cherry-picked and should be left as is.

So I think the cherry-pick is actually not that bad, TBH, but we would like someone to do a proper test.

That said, I would strongly advise against using pre-release interpreter versions in non-root modules. We potentially should just have a check that tests if someone is trying to use a pre-release version in a non-root module and ignore such extension tag class calls.

We have a good version.bzl parser in the latest versions, so backporting that and adding an extra if statement could be also a solution.

That said, maybe as what @rickeylev suggested last is best - just patch the versions.bzl.

[mdorner]

Just to update my understanding the way this breaks seems to be that module A (=grpc) tries to configure the python toolchain with a version that doesn't exist in the latest version of rules_python used in the repository (=my root mod). AFAIU it seems totally fair for grpc to depend on the latest python version at the point in time they write their module. Maybe the symbols in that list should not be the subreleases but the major ones (=3.14 -> 3.140b2)? If they are going to contain symbols like the rc and beta, this is bound to break quite often.

I think the issue title is still pretty accurate: one of these versions being unknown/no longer supported should probably not break the use_extension call. It's another thing to disallow EOL python versions' use entirely than expecting every module to have cleaned up this usage from all their module versions currently in use.

[aignas]

A few observations here:

• Yes, you should not depend on specific versions like 3.14.0b2, depending on 3.14 is better.
• Is grpc providing the dependencies to users that come from the pip.parse calls? In the protobuf repo we found out at some point that the calls should actually have dev_dependency = True.

What is the goal here? I see that only py_library might be used somewhere in user facing targets. Are you using deps coming from pip.parse in user facing bazel targets as well?

[mdorner]

I don't have a goal like this nor control over it. You will have to structurally ensure this in Bazel/rules_python by tracking what becomes part of the API and limiting it/ensure backward compat.

I am a user of both rules_python and grpc and their incompatibility broke me. I'm asking if there's a way to make sure this doesn't happen frequently, which seems likely given the cause of the bug as I understand it now.

[aignas]

I don't have a goal like this nor control over it.

Sorry, I thought you were a maintainer of grpc and I got mistaken here.

I'm asking if there's a way to make sure this doesn't happen frequently, which seems likely given the cause of the bug as I understand it now.

I think this is something that should be highlighted to the grpc team as well because we had a similar issue with the protobuf project, where they use the pip extension in a regular way instead of dev_dependency = True and I don't think there is anything we should design differently - dev and non-dev dependencies is a bazel concept and module authors should be careful about what they do.

[rickeylev]

grpc module: https://github.com/grpc/grpc/blob/master/MODULE.bazel

They're doing some of the same things protobuf is doing.

It's not clear if there are missing dev_dependencies or not.

I'm willing to bet that their pip.parse() calls aren't supposed to be dev_dep=True because they have the same implicit dependency problem protobuf has. i.e. they provide py_grpc_library, and they want it to automatically depend on the proper grpc libraries from pypi for the particular Python version.

Right now, there isn't a great solution to that situation. We have a design to solve that, but haven't gotten around to implementing it. Looking at my email, things are looking promising that we can start working on that, though.