PEP 832: Resolve relative paths in redirect files against the containing directory of physical path of the redirect file (#5199)

Author: brettcannon

peps/pep-0832.rst

@@ -87,14 +87,14 @@ 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
-(which, just like a :file:`.venv` directory, can be a logical or pysical path).
+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
-the user desire a different virtual environment to be used by default by other
+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`
@@ -107,10 +107,14 @@ 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, and if so MUST be relative to the
-directory containing the :file:`.venv` 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 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
@@ -167,9 +171,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
@@ -205,6 +209,13 @@ 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 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
 other tools shouldn't overwrite a :file:`.venv` redirect file they didn't
@@ -465,6 +476,11 @@ this PEP.
 Change History
 ==============
 
+- 26-Oct-2026
+
+  - Require relative paths in a redirect file to be resolved relative to the
+    directory of the physical path of the redirect file
+
 - 24-Sep-2026
 
   - Clarify :file:`.venv` redirect files can be logical or physical paths just