diff --git a/docs/api/rules_python/python/bin/index.md b/docs/api/rules_python/python/bin/index.md
index 8bea6b5..873b644 100644
--- a/docs/api/rules_python/python/bin/index.md
+++ b/docs/api/rules_python/python/bin/index.md
@@ -10,7 +10,8 @@
 A target to directly run a Python interpreter.
 
 By default, it uses the Python version that toolchain resolution matches
-(typically the one marked `is_default=True` in `MODULE.bazel`).
+(typically the one set with `python.defaults(python_version = ...)` in
+`MODULE.bazel`).
 
 This runs a Python interpreter in a similar manner as when running `python3`
 on the command line. It can be invoked using `bazel run`. Remember that in
diff --git a/docs/toolchains.md b/docs/toolchains.md
index a2a2b5b..ada887c 100644
--- a/docs/toolchains.md
+++ b/docs/toolchains.md
@@ -44,7 +44,8 @@
 bazel_dep(name="rules_python", version=...)
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
-python.toolchain(python_version = "3.12", is_default = True)
+python.defaults(python_version = "3.12")
+python.toolchain(python_version = "3.12")
 ```
 
 ### Library modules
@@ -72,7 +73,8 @@
     dev_dependency = True
 )
 
-python.toolchain(python_version = "3.12", is_default=True)
+python.defaults(python_version = "3.12")
+python.toolchain(python_version = "3.12")
 ```
 
 #### Library modules without version constraints
@@ -161,9 +163,13 @@
 # MODULE.bazel
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
+python.defaults(
+    # The environment variable takes precedence if set.
+    python_version = "3.11",
+    python_version_env = "BAZEL_PYTHON_VERSION",
+)
 python.toolchain(
     python_version = "3.11",
-    is_default = True,
 )
 
 python.toolchain(
@@ -264,7 +270,8 @@
 
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
 
-python.toolchain(is_default = True, python_version = "3.10")
+python.defaults(python_version = "3.10")
+python.toolchain(python_version = "3.10")
 
 use_repo(python, "python_3_10", "python_3_10_host")
 ```
diff --git a/examples/bzlmod/MODULE.bazel b/examples/bzlmod/MODULE.bazel
index 69e384e..841c096 100644
--- a/examples/bzlmod/MODULE.bazel
+++ b/examples/bzlmod/MODULE.bazel
@@ -28,10 +28,13 @@
 # We next initialize the python toolchain using the extension.
 # You can set different Python versions in this block.
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.defaults(
+    # Use python.defaults if you have defined multiple toolchain versions.
+    python_version = "3.9",
+    python_version_env = "BAZEL_PYTHON_VERSION",
+)
 python.toolchain(
     configure_coverage_tool = True,
-    # Only set when you have multiple toolchain versions.
-    is_default = True,
     python_version = "3.9",
 )
 
diff --git a/examples/bzlmod/other_module/MODULE.bazel b/examples/bzlmod/other_module/MODULE.bazel
index 959501a..f9d6706 100644
--- a/examples/bzlmod/other_module/MODULE.bazel
+++ b/examples/bzlmod/other_module/MODULE.bazel
@@ -25,14 +25,16 @@
 PYTHON_NAME_311 = "python_3_11"
 
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
+python.defaults(
+    # In a submodule this is ignored
+    python_version = "3.11",
+)
 python.toolchain(
     configure_coverage_tool = True,
     python_version = "3.9",
 )
 python.toolchain(
     configure_coverage_tool = True,
-    # In a submodule this is ignored
-    is_default = True,
     python_version = "3.11",
 )
 
diff --git a/examples/bzlmod_build_file_generation/MODULE.bazel b/examples/bzlmod_build_file_generation/MODULE.bazel
index 9bec25f..b9b428d 100644
--- a/examples/bzlmod_build_file_generation/MODULE.bazel
+++ b/examples/bzlmod_build_file_generation/MODULE.bazel
@@ -46,9 +46,13 @@
 
 # We next initialize the python toolchain using the extension.
 # You can set different Python versions in this block.
+python.defaults(
+    # The environment variable takes precedence if set.
+    python_version = "3.9",
+    python_version_env = "BAZEL_PYTHON_VERSION",
+)
 python.toolchain(
     configure_coverage_tool = True,
-    is_default = True,
     python_version = "3.9",
 )
 
diff --git a/examples/multi_python_versions/MODULE.bazel b/examples/multi_python_versions/MODULE.bazel
index 8514036..4e4a047 100644
--- a/examples/multi_python_versions/MODULE.bazel
+++ b/examples/multi_python_versions/MODULE.bazel
@@ -17,8 +17,6 @@
 )
 python.toolchain(
     configure_coverage_tool = True,
-    # Only set when you have mulitple toolchain versions.
-    is_default = True,
     python_version = "3.9",
 )
 python.toolchain(
diff --git a/python/extensions/python.bzl b/python/extensions/python.bzl
index abd5080..b8b755e 100644
--- a/python/extensions/python.bzl
+++ b/python/extensions/python.bzl
@@ -20,10 +20,8 @@
 
 ```starlark
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
-python.toolchain(
-    is_default = True,
-    python_version = "3.11",
-)
+python.defaults(python_version = "3.11")
+python.toolchain(python_version = "3.11")
 use_repo(python, "python_3_11")
 ```
 
diff --git a/python/private/python.bzl b/python/private/python.bzl
index 24ce38a..a7e2576 100644
--- a/python/private/python.bzl
+++ b/python/private/python.bzl
@@ -223,7 +223,7 @@
     # A default toolchain is required so that the non-version-specific rules
     # are able to match a toolchain.
     if default_toolchain == None:
-        fail("No default Python toolchain configured. Is rules_python missing `is_default=True`?")
+        fail("No default Python toolchain configured. Is rules_python missing `python.defaults()`?")
     elif default_toolchain.python_version not in global_toolchain_versions:
         fail('Default version "{python_version}" selected by module ' +
              '"{module_name}", but no toolchain with that version registered'.format(
@@ -891,10 +891,8 @@
 syntax:
 ```starlark
 python = use_extension("@rules_python//python/extensions:python.bzl", "python")
-python.toolchain(
-    is_default = True,
-    python_version = "3.11",
-)
+python.defaults(python_version = "3.11")
+python.toolchain(python_version = "3.11")
 
 use_repo(python, my_python_name = "python_3_11")
 ```
@@ -930,7 +928,7 @@
 
 :::{versionchanged} 1.4.0
 This setting is ignored if the default version is set using the `defaults`
-tag class.
+tag class (encouraged).
 :::
 """,
         ),