From: Harjoth Khara Date: Mon, 22 Jun 2026 14:05:03 +0000 (-0700) Subject: gh-124113: Clarify venv target directory reuse (#151419) X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=614e3ec0c63291615b792587fedd46ae47f0a9cb;p=thirdparty%2FPython%2Fcpython.git gh-124113: Clarify venv target directory reuse (#151419) * gh-124113: Clarify venv target directory reuse * gh-124113: Refine venv reuse wording * gh-124113: State that --clear also deletes non-venv files --- diff --git a/Doc/library/venv.rst b/Doc/library/venv.rst index 8bb267d5a0b9..1ad2401fe2f3 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. +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. @@ -126,7 +129,9 @@ 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, + including files that were not created by ``venv``, + before environment creation. .. option:: --upgrade