From 86ed8ebdde862541e7d02f2d854e8840ab19b21f Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 9 Oct 2026 16:35:57 -0700 Subject: [PATCH 1/6] Tighten rules to avoid relative path ambiguity arount symlinks --- peps/pep-0832.rst | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/peps/pep-0832.rst b/peps/pep-0832.rst index b26a876c039..cc8ef0a82c7 100644 --- a/peps/pep-0832.rst +++ b/peps/pep-0832.rst @@ -88,14 +88,14 @@ logical paths should be resolved to their physical equivalent before use. Instead of a directory containing a virtual environment, the root of a project MAY have a :file:`.venv` redirect file. This file acts as a pointer to where -the (current) virtual environment to be used for the project is located -(which, just like a :file:`.venv` directory, can be a logical or pysical path). -This virtual environment may not be the only environment associated with the -project, but it is considered the preferred virtual environment to use -*at the moment* by other tools. The tool managing the virtual environment -SHOULD update any :file:`.venv` redirect file as appropriate when the tool or -the user desire a different virtual environment to be used by default by other -tools. +the (current) virtual environment to be used for the project is located. The +file itself MUST NOT be a logical path; its containing directory and any +parent directories MAY be logical paths. This virtual environment may not be +the only environment associated with the project, but it is considered the +preferred virtual environment to use *at the moment* by other tools. The tool +managing the virtual environment SHOULD update any :file:`.venv` redirect file +as appropriate when the tool or the user desires a different virtual +environment to be used by default by other tools. Tools looking for a virtual environment SHOULD look for either a :file:`.venv` directory or a :file:`.venv` redirect file. IF a tool chooses to search parent @@ -109,8 +109,8 @@ that only contains a newline is considered invalid. The line in the :file:`.venv` redirect file MUST point to a directory containing a virtual environment when being written. The path MAY use POSIX path separators-- ``/`` --regardless of what the operating system's native path -separator is. The path MAY be relative, and if so MUST be relative to the -directory containing the :file:`.venv` file. +separator is. The path MAY be relative; IF the path is relative THEN it MUST be +resolved relative to the physical directory containing the redirect file. With regard to committing a :file:`.venv` redirect file to version control, it MAY be done when the location of the virtual environment is considered static @@ -205,6 +205,15 @@ name or ownership of the virtual environment, but e.g., virtual environments have the prompt recorded in :file:`pyvenv.cfg`, so it does not need to be listed separately from the environment where it may become stale. +The discussion identified ambiguity about resolving relative paths in a +:file:`.venv` redirect file when logical paths are involved. A logical path +could refer to the redirect file itself or to any part of its containing +directory. Two requirements address this. First, the redirect file itself MUST +NOT be a symbolic link, avoiding ambiguity about whether relative paths are +resolved against its logical or physical location. Second, the containing +directory MUST be resolved to a physical path before any relative path in the +redirect file is resolved. + While some projects may have multiple virtual environments available, the concept of a current or default virtual environment is a constant. And saying other tools shouldn't overwrite a :file:`.venv` redirect file they didn't @@ -465,6 +474,11 @@ this PEP. Change History ============== +- XX-Oct-2026 + - Require :file:`.venv` redirect files not be a symlink + - Require relative paths in a redirect file to be resolved relative to the + physical directory containing the file + - 24-Sep-2026 - Clarify :file:`.venv` redirect files can be logical or physical paths just From bdba7a4156231b39ead9bdd189267654095f43aa Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 16 Oct 2026 11:50:25 -0700 Subject: [PATCH 2/6] Let redirect files be symlinks --- peps/pep-0832.rst | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/peps/pep-0832.rst b/peps/pep-0832.rst index cc8ef0a82c7..cd9ec0ba6ce 100644 --- a/peps/pep-0832.rst +++ b/peps/pep-0832.rst @@ -88,14 +88,13 @@ logical paths should be resolved to their physical equivalent before use. Instead of a directory containing a virtual environment, the root of a project MAY have a :file:`.venv` redirect file. This file acts as a pointer to where -the (current) virtual environment to be used for the project is located. The -file itself MUST NOT be a logical path; its containing directory and any -parent directories MAY be logical paths. This virtual environment may not be -the only environment associated with the project, but it is considered the -preferred virtual environment to use *at the moment* by other tools. The tool -managing the virtual environment SHOULD update any :file:`.venv` redirect file -as appropriate when the tool or the user desires a different virtual -environment to be used by default by other tools. +the (current) virtual environment to be used for the project is located. This +virtual environment may not be the only environment associated with the +project, but it is considered the preferred virtual environment to use +*at the moment* by other tools. The tool managing the virtual environment +SHOULD update any :file:`.venv` redirect file as appropriate when the tool or +the user desires a different virtual environment to be used by default by other +tools. Tools looking for a virtual environment SHOULD look for either a :file:`.venv` directory or a :file:`.venv` redirect file. IF a tool chooses to search parent @@ -107,10 +106,11 @@ either ``\n`` or ``\r\n`` is allowed and MUST be ignored. An empty file or one that only contains a newline is considered invalid. The line in the :file:`.venv` redirect file MUST point to a directory -containing a virtual environment when being written. The path MAY use POSIX -path separators-- ``/`` --regardless of what the operating system's native path -separator is. The path MAY be relative; IF the path is relative THEN it MUST be -resolved relative to the physical directory containing the redirect file. +containing a virtual environment at the time of being written. The path MAY use +POSIX path separators-- ``/`` --regardless of what the operating system's +native path separator is. The path MAY be relative; IF the path is relative +THEN it MUST be resolved relative to the physical path of the :file:`.venv` +redirect file. With regard to committing a :file:`.venv` redirect file to version control, it MAY be done when the location of the virtual environment is considered static @@ -475,9 +475,8 @@ Change History ============== - XX-Oct-2026 - - Require :file:`.venv` redirect files not be a symlink - Require relative paths in a redirect file to be resolved relative to the - physical directory containing the file + physical path of the redirect file - 24-Sep-2026 From 91c7f549906840be3c129f2cd2241f4509c7a26d Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 16 Oct 2026 11:56:35 -0700 Subject: [PATCH 3/6] Minor rewording --- peps/pep-0832.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/peps/pep-0832.rst b/peps/pep-0832.rst index cd9ec0ba6ce..7456cd9be36 100644 --- a/peps/pep-0832.rst +++ b/peps/pep-0832.rst @@ -167,9 +167,9 @@ to tell other tools where to find the virtual environment to use. That's the purpose of the :file:`.venv` redirect file. The file itself is hidden as it isn't a critical aspect of the project (environments themselves can be viewed as implementation details). The file name was chosen to match the :file:`.venv` -directory name as the purpose of a path with that name is already well known. -As well, it is already broadly ignored by projects, so it won't lead to -projects suddenly having a new file that they may accidentally commit. +directory name as the purpose of a directory with that name is already +well-known. As well, it is already broadly ignored by projects, so it won't +lead to projects suddenly having a new file that they may accidentally commit. The :file:`.venv` redirect file format is simple to allow for easy manipulation. It is easy to write a line to a :file:`.venv` file via the From 015004a1c620498262ab16cbffef65c0d476e840 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 16 Oct 2026 11:59:48 -0700 Subject: [PATCH 4/6] Update the Rationale --- peps/pep-0832.rst | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/peps/pep-0832.rst b/peps/pep-0832.rst index 7456cd9be36..262a01ef4b4 100644 --- a/peps/pep-0832.rst +++ b/peps/pep-0832.rst @@ -206,13 +206,11 @@ have the prompt recorded in :file:`pyvenv.cfg`, so it does not need to be listed separately from the environment where it may become stale. The discussion identified ambiguity about resolving relative paths in a -:file:`.venv` redirect file when logical paths are involved. A logical path -could refer to the redirect file itself or to any part of its containing -directory. Two requirements address this. First, the redirect file itself MUST -NOT be a symbolic link, avoiding ambiguity about whether relative paths are -resolved against its logical or physical location. Second, the containing -directory MUST be resolved to a physical path before any relative path in the -redirect file is resolved. +:file:`.venv` redirect file when logical paths for the redirect file itself are +involved. A logical path could refer to the redirect file itself or to any part +of its containing directory. To solve the ambiguity, the path to the redirect +file MUST be resolved to a physical path before any relative path contained in +the redirect file is resolved. While some projects may have multiple virtual environments available, the concept of a current or default virtual environment is a constant. And saying From 39f160afb6a692efa4f7ed2dc96bc9673618be42 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 26 Oct 2026 16:00:32 -0700 Subject: [PATCH 5/6] Clarify relative paths resolve to the directory containing the redirect file --- peps/pep-0832.rst | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/peps/pep-0832.rst b/peps/pep-0832.rst index 262a01ef4b4..2ede16184f2 100644 --- a/peps/pep-0832.rst +++ b/peps/pep-0832.rst @@ -87,9 +87,10 @@ logical path to a directory containing a virtual environment, nor whether logical paths should be resolved to their physical equivalent before use. Instead of a directory containing a virtual environment, the root of a project -MAY have a :file:`.venv` redirect file. This file acts as a pointer to where -the (current) virtual environment to be used for the project is located. This -virtual environment may not be the only environment associated with the +MAY have a :file:`.venv` redirect file (which, just like a :file:`.venv` +directory, can be a logical or pysical path). This file acts as a pointer to +where the (current) virtual environment to be used for the project is located. +This virtual environment may not be the only environment associated with the project, but it is considered the preferred virtual environment to use *at the moment* by other tools. The tool managing the virtual environment SHOULD update any :file:`.venv` redirect file as appropriate when the tool or @@ -109,8 +110,11 @@ The line in the :file:`.venv` redirect file MUST point to a directory containing a virtual environment at the time of being written. The path MAY use POSIX path separators-- ``/`` --regardless of what the operating system's native path separator is. The path MAY be relative; IF the path is relative -THEN it MUST be resolved relative to the physical path of the :file:`.venv` -redirect file. +THEN it MUST be resolved relative to the directory containing the :file:`.venv` +redirect file based on the file's physical path (e.g., for a redirect file with +a logical path of :file:`/my/.venv` and a physical path of +:file:`/some/project/.venv`, the file contents of ``../target`` resolves to +:file:`/some/target`). With regard to committing a :file:`.venv` redirect file to version control, it MAY be done when the location of the virtual environment is considered static @@ -472,9 +476,10 @@ this PEP. Change History ============== -- XX-Oct-2026 +- 26-Oct-2026 + - Require relative paths in a redirect file to be resolved relative to the - physical path of the redirect file + directory of physical path of the redirect file - 24-Sep-2026 From 5721bae1157a37ab3257166fc9e4e42721359715 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 26 Oct 2026 16:02:15 -0700 Subject: [PATCH 6/6] Grammar fix --- peps/pep-0832.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0832.rst b/peps/pep-0832.rst index 2ede16184f2..74d00d2154e 100644 --- a/peps/pep-0832.rst +++ b/peps/pep-0832.rst @@ -479,7 +479,7 @@ Change History - 26-Oct-2026 - Require relative paths in a redirect file to be resolved relative to the - directory of physical path of the redirect file + directory of the physical path of the redirect file - 24-Sep-2026