diff --git a/docs/src/repl.md b/docs/src/repl.md
index 255e1a40ad..9eb6428443 100644
--- a/docs/src/repl.md
+++ b/docs/src/repl.md
@@ -73,12 +73,6 @@ style.use('ggplot')
 
 #### Global environment
 
-<div class="warning">
-
-On macOS, your system Python will _not_ work. Either set up [pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) or use a virtual environment.
-
-</div>
-
 To set up your current Python to have an available kernel, run:
 
 ```sh
@@ -102,6 +96,8 @@ pip install ipykernel
 python -m ipykernel install --user --name myenv --display-name "Python (myenv)"
 ```
 
+> Note: **On macOS, your system Python will _not_ work**. Either set up [pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation) or use a virtual environment. Zed uses separate selections for the Python [toolchain](./configuring-languages.md#toolchains) and REPL kernel. If diagnostics differ from the REPL, align the toolchain with the kernel using {#action toolchain::Select}. Read more about the [toolchain selector for Python](./languages/python.md#selecting-a-toolchain).
+
 ### R (Ark Kernel) {#r-ark}
 
 Install [Ark](https://github.com/posit-dev/ark/releases) by downloading the release for your operating system. For example, for macOS just unpack `ark` binary and put it into `/usr/local/bin`. Then run: