From 09319363b2cf0e384257a8c2634f5ecde325ebbb Mon Sep 17 00:00:00 2001 From: harjoth Date: Fri, 12 Jun 2026 11:16:05 -0700 Subject: [PATCH 1/3] gh-124113: Clarify venv target directory reuse --- Doc/library/venv.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 8bb267d5a0b9588..00f1614e9e6c1e7 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -77,6 +77,9 @@ containing a copy or symlink of the Python executable It also creates a :file:`lib/pythonX.Y/site-packages` subdirectory (on Windows, this is :file:`Lib\\site-packages`). If an existing directory is specified, it will be re-used. +This does not leave the directory unchanged: ``venv`` creates or replaces +environment files in the target directory. Use a dedicated directory for the +virtual environment, and avoid placing project files in it. .. versionchanged:: 3.5 The use of ``venv`` is now recommended for creating virtual environments. @@ -126,7 +129,8 @@ The command, if run with ``-h``, will show the available options:: .. option:: --clear - Delete the contents of the environment directory if it already exists, before environment creation. + Delete all contents of the environment directory if it already exists, + before environment creation. .. option:: --upgrade From c25ebb3b53844891364266c87ae9c97f3cca62e7 Mon Sep 17 00:00:00 2001 From: harjoth Date: Fri, 12 Jun 2026 11:55:09 -0700 Subject: [PATCH 2/3] gh-124113: Refine venv reuse wording --- Doc/library/venv.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 00f1614e9e6c1e7..af1afe77fbe1c23 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -77,9 +77,9 @@ containing a copy or symlink of the Python executable It also creates a :file:`lib/pythonX.Y/site-packages` subdirectory (on Windows, this is :file:`Lib\\site-packages`). If an existing directory is specified, it will be re-used. -This does not leave the directory unchanged: ``venv`` creates or replaces -environment files in the target directory. Use a dedicated directory for the -virtual environment, and avoid placing project files in it. +Reusing an existing directory does not leave it unchanged: ``venv`` may create, +update, or replace files in the target directory. Use a dedicated directory for +the virtual environment, and avoid placing project files directly inside it. .. versionchanged:: 3.5 The use of ``venv`` is now recommended for creating virtual environments. From de5f11a684bc2936b66da8f6a9c3e6c66eea378c Mon Sep 17 00:00:00 2001 From: harjoth Date: Fri, 12 Jun 2026 12:32:34 -0700 Subject: [PATCH 3/3] gh-124113: State that --clear also deletes non-venv files --- Doc/library/venv.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index af1afe77fbe1c23..1ad2401fe2f3f31 100644 --- a/Doc/library/venv.rst +++ b/Doc/library/venv.rst @@ -130,6 +130,7 @@ The command, if run with ``-h``, will show the available options:: .. option:: --clear Delete all contents of the environment directory if it already exists, + including files that were not created by ``venv``, before environment creation. .. option:: --upgrade