gh-136880: Add warning about PYTHONPATH

[glennglazer]

Warn people that PYTHONPATH is inherited in the venv, this can produce unexpected results such as the wrong library version (if system is different than venv requirements) or even completely incompatible references.

• Issue: Default venv activate does not unset PYTHONPATH #136880

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33082536 | 📁 Comparing b8949b7 against main (5c13217)

  🔍 Preview build  

21 files changed · + 1 added · ± 20 modified

+ Added

• library/asyncio-threading.html

± Modified

• c-api/coro.html
• c-api/gen.html
• c-api/memory.html
• c-api/module.html
• c-api/weakref.html
• deprecations/c-api-pending-removal-in-3.18.html
• deprecations/index.html
• library/argparse.html
• library/asyncio.html
• library/collections.abc.html
• and 10 more...

[vsajip]

Where do you get that PYTHONHOME is managed by the activated venv?

$ python3.14 -m venv /tmp/foo
$ echo $PYTHONHOME

$ source /tmp/foo/bin/activate
$ echo $PYTHONHOME

I don't think the first sentence is correct. You could validly say "Note that activating a virtual environment does not alter the PYTHONPATH ..."

[glennglazer]

Where do you get that PYTHONHOME is managed by the activated venv?

$ python3.14 -m venv /tmp/foo
$ echo $PYTHONHOME

$ source /tmp/foo/bin/activate
$ echo $PYTHONHOME

I don't think the first sentence is correct. You could validly say "Note that activating a virtual environment does not alter the PYTHONPATH ..."

That was the guidance I received in the issue, see #136880 (comment) .

I'm perfectly fine with your suggested change.