fix: avoid stage1 bootstrap stdlib shadowing

.bazelci/presubmit.yml

@@ -84,6 +84,9 @@ buildifier:
   coverage_targets: ["..."]
 .coverage_targets_example_bzlmod_build_file_generation: &coverage_targets_example_bzlmod_build_file_generation
   coverage_targets: ["//:bzlmod_build_file_generation_test"]
+.coverage_targets_bootstrap: &coverage_targets_bootstrap
+  coverage_targets:
+    - //tests/bootstrap_impls:stdlib_shadowing_system_python_test
 .coverage_targets_example_multi_python: &coverage_targets_example_multi_python
   coverage_targets:
     - //tests:my_lib_3_10_test
@@ -216,6 +219,7 @@ tasks:
     bazel: 7.x
   ubuntu:
     <<: *reusable_config
+    <<: *coverage_targets_bootstrap
     name: "Default: Ubuntu, Bazel {bazel}"
     platform: ubuntu2204
     bazel: ${{ bazel }}

news/3854.fixed.md

@@ -0,0 +1,2 @@
+(bootstrap) Fixed stage 1 bootstrap imports when target outputs shadow standard
+library modules.

python/private/python_bootstrap_template.txt

@@ -5,13 +5,31 @@ from __future__ import absolute_import
 from __future__ import division
 from __future__ import print_function
 
+import sys
+
+# By default, Python prepends the directory containing this script to
+# sys.path. The stage 1 bootstrap only needs stdlib modules before it
+# re-execs into the configured runtime, so avoid resolving imports from the
+# target's output or runfiles package directory. This matters when that
+# directory contains files with stdlib names, such as shutil.py or types.py.
+#
+# Python 3.11 introduced PYTHONSAFEPATH (-P), which disables the unsafe prepend.
+# Isolated mode (-I) also disables it, including on older interpreters without
+# safe_path. In either case, sys.path[0] is not the script directory and should
+# be preserved.
+if (
+    not getattr(sys.flags, "safe_path", False) and
+    not getattr(sys.flags, "isolated", False) and
+    sys.path
+):
+  del sys.path[0]
+
 # Generated file from @rules_python//python/private:python_bootstrap_template.txt
 
 from os.path import abspath, dirname, join, basename, normpath
 import os
 import shutil
 import subprocess
-import sys
 
 # NOTE: The sentinel strings are split (e.g., "%stage2" + "_bootstrap%") so that
 # the substitution logic won't replace them. This allows runtime detection of

python/private/stage2_bootstrap_template.py

@@ -9,11 +9,16 @@
 # and is a special case of #7091.
 #
 # Python 3.11 introduced an PYTHONSAFEPATH (-P) option that disables this
-# behaviour, which we set in the stage 1 bootstrap.
+# behaviour, which we set in the stage 1 bootstrap. Isolated mode (-I) also
+# disables it, including on older interpreters without safe_path.
 # So the prepended entry needs to be removed only if the above option is either
 # unset or not supported by the interpreter.
 # NOTE: This can be removed when Python 3.10 and below is no longer supported
-if not getattr(sys.flags, "safe_path", False):
+if (
+    not getattr(sys.flags, "safe_path", False)
+    and not getattr(sys.flags, "isolated", False)
+    and sys.path
+):
     del sys.path[0]
 
 import contextlib
@@ -539,8 +544,10 @@ def main():
         # means only other generated files are importable (not source files).
         #
         # To replicate this behavior, we add main's directory within the runfiles
-        # when safe path isn't enabled.
-        if not getattr(sys.flags, "safe_path", False):
+        # when safe path or isolated mode isn't enabled.
+        if not getattr(sys.flags, "safe_path", False) and not getattr(
+            sys.flags, "isolated", False
+        ):
             prepend_path_entries = [
                 os.path.join(runfiles_root, os.path.dirname(main_rel_path))
             ]

tests/bootstrap_impls/BUILD.bazel

@@ -136,6 +136,32 @@ py_reconfig_test(
     main = "sys_path_order_test.py",
 )
 
+genrule(
+    name = "stdlib_shadowing_outputs",
+    outs = [
+        "shutil.py",
+        "types.py",
+    ],
+    cmd = """
+cat > $(@D)/shutil.py <<'PY'
+raise RuntimeError("target output shutil.py shadowed the stdlib shutil module")
+PY
+cat > $(@D)/types.py <<'PY'
+raise RuntimeError("target output types.py shadowed the stdlib types module")
+PY
+""",
+)
+
+py_reconfig_test(
+    name = "stdlib_shadowing_system_python_test",
+    srcs = [
+        "stdlib_shadowing_test.py",
+        ":stdlib_shadowing_outputs",
+    ],
+    bootstrap_impl = "system_python",
+    main = "stdlib_shadowing_test.py",
+)
+
 py_reconfig_test(
     name = "main_module_test",
     srcs = ["main_module.py"],

tests/bootstrap_impls/stdlib_shadowing_test.py

@@ -0,0 +1,20 @@
+# Copyright 2026 The Bazel Authors. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Verifies stage 1 bootstrap stdlib imports cannot be shadowed."""
+
+
+def test_bootstrap_reached_main():
+    # If stage 1 imports target outputs such as shutil.py instead of stdlib
+    # modules, the process fails before this test module is executed.
+    pass