PEP 832 – Virtual environment discovery | peps.python.org
PEP 832 – Virtual environment discovery PEP 832 – Virtual environment discovery Author : Brett Cannon <brett at python.org> Discussions-To : Discourse thread Status : Draft Type : Standards Track Topic : Packaging Created : 19-Jan-2026 Post-History : 15-Apr-2026 23-Apr-2026 31-Jul-2026 10-Aug-2026 08-Sep-2026 Table of Contents Abstract Motivation Specification Rationale Example Project Support for this PEP Backwards Compatibility Security Implications How to Teach This Reference Implementation Rejected Ideas Use a name other than .venv Recording what tool manages an environment Using a more structured format Storing the locations in pyproject.toml Leave .venv redirect files out of the PEP Support a file name suffix for .venv redirect files Support multiple virtual environments Support other environment types Deferred Ideas Acknowledgements Change History Copyright Abstract This PEP sets out to help make the discovery of a project’s preferred virtual environment easier.
By providing a default location to look for a virtual environment as already supported by most tools as well as an easy way for workflow tools to point to a virtual environment placed somewhere other than the default location, tools will have a way to find the project’s preferred virtual environment. Motivation Imagine you are on your Mac laptop and you double-click your desktop shortcut to launch Emacs (feel free to substitute “Mac” and “Emacs” with your preferred OS and editor, respectively).
You open the directory for your project in Emacs. Now, how is Emacs (or any other tool for that matter) supposed to know where the environments for your project are if they already exist? There’s no possible detection of an activated virtual environment via the VIRTUAL_ENV environment variable because you didn’t launch it from a terminal. You potentially could scan all subdirectories for a pyvenv.cfg file to find a virtual environment, but that assumes the virtual environments are kept locally with the project.
What are tools like code editors, which need access to the environments being used to provide functionality like auto-complete, to do when there is currently no standardized way to tell anyone where the preferred virtual environment is? Currently, tools like editors have to hard-code a search algorithm for every tool that they choose to support. As well, the tool can document any conventions they support, but that assumes you or the tool you use to manage your virtual environments follow those conventions, which, being conventions, are not written down anywhere as a standard.
And this is not a hypothetical issue. The author of this PEP was the dev manager for Python support in VS Code for 7 years and saw firsthand the struggling of users and constant feature requests for finding one’s environments for a project. This issue is also not restricted to code editors. Other tools have a need to access a project’s environment to know what is installed. One example is type checkers which need access to the packages that are installed to appropriately gather type annotations for 3rd-party code in order to type check the user’s code.
The goal of this PEP is to provide a specification for tools which create/manage virtual environments in order to tell other tools where the preferred/active virtual environment for a project is. And in the case of a project which has multiple virtual environments, this PEP is meant to allow for specifying the default environment to use so users are not forced to make a choice of environment if they do not want to make such a decision (e.g. at first launch of their code editor).
Please note this PEP neither condones nor discourages having multiple environments for a single project; it is neutral as to whether having a single environment or multiple ones is good or bad. It also does not condone one environment type over another. Specification This PEP does not define what the “root of a project” means, but the assumption is that it is the directory one would open in their code editor to work on a project’s code.
This could be the directory where the project’s pyproject.toml lives, or potentially the top directory of a monorepo. The virtual environment for a project MAY be a directory named .venv (i.e., .venv/pyvenv.cfg will exist within the directory, which can be used to detect the existence of a virtual environment) in the root of the project. This PEP makes no judgment whether .venv is a physical or 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 .venv redirect file (which, just like a .venv directory, can be a logical or physical 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 .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 .venv directory or a .venv redirect file. IF a tool chooses to search parent directories, THEN the closest .venv in either form SHOULD be selected. A .venv redirect file MUST be encoded using UTF-8 (the UTF-8 BOM MUST NOT be used).
The file MUST only contain a single line. A trailing newline of 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 .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 directory containing the .venv redirect file based on the file’s physical path (e.g., for a redirect file with a logical path of /my/.venv and a physical path of /some/project/.venv , the file contents of ../target resolves to /some/target ). With regard to committing a .venv redirect file to version control, it MAY be done when the location of the virtual environment is considered static for a project once it is set up.
For instance, some projects that use tox have a “dev” environment defined in their configuration that ends up at .tox/dev . Setting a .venv redirect file to point to that virtual environment and checking in the file is reasonable. The same goes for a project that is only worked on within a container where the location of the virtual environment is controlled and thus static on the file system. The guidance of NOT committing your actual virtual environment to version control is unchanged by this PEP.
IF a tool can detect that an environment is already in use (e.g. the VIRTUAL_ENV environment variable is set), THEN tools SHOULD respect the user’s choice and use the activated/in-use environment over the default environment when no previous environment selection has occurred or the tool doesn’t have its own justification for ignoring the user’s supposed choice. Tools MAY choose to override even a previous environment selection if an environment is detected as activated/in use.
This PEP is choosing NOT to take a position on what to do if .venv is invalid (whether it’s a directory or a file). It is up to the tool encountering the invalid directory/file to decide how best to handle the situation. The expectation, though, is the invalid directory/file will not simply be ignored. Rationale Explicitly supporting .venv is to codify what’s already a convention: Poetry will detect a virtual environment in such a l
The rest of this page is on the live site.