From 8628b43b204605cd431a01dc31b832af0d84a9de Mon Sep 17 00:00:00 2001 From: glennglazer Date: Mon, 8 Jun 2026 10:48:22 -0700 Subject: [PATCH 1/5] Add warning about PYTHONPATH See conversation here: https://github.com/python/cpython/issues/136880 for the request for this documentation update. --- Doc/tutorial/venv.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst index f362e1943b666f..d19ce866cbd68d 100644 --- a/Doc/tutorial/venv.rst +++ b/Doc/tutorial/venv.rst @@ -88,6 +88,8 @@ For example: '~/envs/tutorial-env/lib/python3.5/site-packages'] >>> +Note that the activated virtual environment manages the :term:`PYTHONHOME` environment variable to find the specific version of Python that is requested. It does not alter the :term:`PYTHONPATH` variable in any way. This may lead to unexpected results if the path includes references to code which is incompatible with the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH`` in bash or the equivalent for the shell you are using. + To deactivate a virtual environment, type:: deactivate From 431f247acf72360c408ab40327eaf4d22cdc9bf7 Mon Sep 17 00:00:00 2001 From: glennglazer Date: Mon, 8 Jun 2026 11:23:34 -0700 Subject: [PATCH 2/5] remove undefined terms replace with simple highlighting --- Doc/tutorial/venv.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst index d19ce866cbd68d..3cd6a397d0e04e 100644 --- a/Doc/tutorial/venv.rst +++ b/Doc/tutorial/venv.rst @@ -88,7 +88,7 @@ For example: '~/envs/tutorial-env/lib/python3.5/site-packages'] >>> -Note that the activated virtual environment manages the :term:`PYTHONHOME` environment variable to find the specific version of Python that is requested. It does not alter the :term:`PYTHONPATH` variable in any way. This may lead to unexpected results if the path includes references to code which is incompatible with the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH`` in bash or the equivalent for the shell you are using. +Note that the activated virtual environment manages the ``PYTHONHOME`` environment variable to find the specific version of Python that is requested. It does not alter the ``PYTHONPATH`` variable in any way. This may lead to unexpected results if the path includes references to code which is incompatible with the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH`` in bash or the equivalent for the shell you are using. To deactivate a virtual environment, type:: From 8cffed130dbbea08f26110ba208eb8acfe365931 Mon Sep 17 00:00:00 2001 From: glennglazer Date: Wed, 10 Jun 2026 10:41:17 -0700 Subject: [PATCH 3/5] Update venv.rst to clarify PYTHONPATH behavior per review comments Clarified that the activated virtual environment does not alter the PYTHONPATH variable. --- Doc/tutorial/venv.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst index 3cd6a397d0e04e..49c26482b3d51d 100644 --- a/Doc/tutorial/venv.rst +++ b/Doc/tutorial/venv.rst @@ -88,7 +88,7 @@ For example: '~/envs/tutorial-env/lib/python3.5/site-packages'] >>> -Note that the activated virtual environment manages the ``PYTHONHOME`` environment variable to find the specific version of Python that is requested. It does not alter the ``PYTHONPATH`` variable in any way. This may lead to unexpected results if the path includes references to code which is incompatible with the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH`` in bash or the equivalent for the shell you are using. +Note that the activated virtual environment does not alter the ``PYTHONPATH`` variable in any way. This may lead to unexpected results if the path includes references to code which is incompatible with the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH`` in bash or the equivalent for the shell you are using. To deactivate a virtual environment, type:: From 7ec6a513f48f1182b0218b66fa674e65c8128b12 Mon Sep 17 00:00:00 2001 From: glennglazer Date: Wed, 10 Jun 2026 13:00:26 -0700 Subject: [PATCH 4/5] Wrap long line in the PYTHONPATH note in venv.rst per review comments Reformat note about PYTHONPATH and virtual environments for clarity. --- Doc/tutorial/venv.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst index 49c26482b3d51d..7543cd2ffccd82 100644 --- a/Doc/tutorial/venv.rst +++ b/Doc/tutorial/venv.rst @@ -88,7 +88,10 @@ For example: '~/envs/tutorial-env/lib/python3.5/site-packages'] >>> -Note that the activated virtual environment does not alter the ``PYTHONPATH`` variable in any way. This may lead to unexpected results if the path includes references to code which is incompatible with the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH`` in bash or the equivalent for the shell you are using. +Note that the activated virtual environment does not alter the ``PYTHONPATH`` variable in any way. +This may lead to unexpected results if the path includes references to code which is incompatible with +the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH`` +in bash or the equivalent for the shell you are using. To deactivate a virtual environment, type:: From b8949b7b48d645ed6ceea736eb5d85e7b65039b9 Mon Sep 17 00:00:00 2001 From: glennglazer Date: Wed, 10 Jun 2026 13:05:39 -0700 Subject: [PATCH 5/5] remove trailing whitespace remove trailing whitespace --- Doc/tutorial/venv.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/tutorial/venv.rst b/Doc/tutorial/venv.rst index 7543cd2ffccd82..6b6b8a768e3f58 100644 --- a/Doc/tutorial/venv.rst +++ b/Doc/tutorial/venv.rst @@ -88,9 +88,9 @@ For example: '~/envs/tutorial-env/lib/python3.5/site-packages'] >>> -Note that the activated virtual environment does not alter the ``PYTHONPATH`` variable in any way. -This may lead to unexpected results if the path includes references to code which is incompatible with -the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH`` +Note that the activated virtual environment does not alter the ``PYTHONPATH`` variable in any way. +This may lead to unexpected results if the path includes references to code which is incompatible with +the Python version the virtual environment is using. The best practice is to ``unset PYTHONPATH`` in bash or the equivalent for the shell you are using. To deactivate a virtual environment, type::