Requiring a virtual environment by default

When a user runs an installer without an active virtual environment, the installer SHOULD print an error message and exit with a non-zero exit code.

The error message SHOULD inform the user that a virtual environment is required, SHOULD provide shell-specific instructions on how to create and activate a virtual environment named .venv, and SHOULD provide a link to a documentation page that explains how to create and activate a virtual environment.

See Implementation Notes for more details.

Opting out of virtual environments

The installer SHOULD also provide a explicit opt-in to disable this requirement, allowing an end user to use it outside of a virtual environment. If the installer does not provide this functionality, it SHOULD mention this in the error message and documentation page.

Consistent timeline for the change

Installers MAY choose to implement this default behaviour on any Python versions, but SHOULD implement it on Python 3.13 or newer.

Detecting an active virtual environment

As discussed in PEP 668, the logic for robustly detecting a virtual environment is something like:

def is_virtual_environment():
    return sys.base_prefix != sys.prefix or hasattr(sys, "real_prefix")

Documentation on using a virtual environment

Package installers are expected to provide a link to a documentation page in the error message.

Ideally, such a documentation page would explain what virtual environments are, why they are required, and how to create and activate a virtual environment using venv. It should include instructions for the most common shells and platforms.

Such a documentation page should be made available in the Python Packaging User Guide to reduce duplicated effort across installers for covering this topic.

Do not specify a name for the virtual environment directory

Using a consistent name for the virtual environment directory is important for a few reasons:

1. It makes it easier for users to find the virtual environment directory, and to activate it.
2. It removes a decision point for new users, since they do not need to decide on a name for the virtual environment directory.
3. It creates a clear convention within the ecosystem, which makes it easier for users to find documentation.
4. It ensures consistency across different tools, so that differences in the error messages do not confuse users.

Use a different name for the virtual environment directory

Functionally, the directory name does not matter much as long as there is a single consistent suggestion.

The name .venv was picked since it:

1. does not conflict with any valid Python import name
2. does not conflict venv module in the standard library
3. has pre-existing usage in the Python community
4. has support for auto-detection in common text editors
5. can be typed without modifier keys on common keyboard layouts

Do not couple tooling behaviour with a Python version

This PEP creates a coupling between the behaviour of installers and the Python version.

This is already a rollout mechanism being used for behaviour changes in the installation tooling. For example, pip on Python 3.11 will use importlib.metadata instead of pkg_resources for parsing/fetching package metadata, and sysconfig instead of distutils.sysconfig for getting the paths to unpack wheels into.

The difference with those cases is that they’re supposed to be largely transparent to end users. This PEP is proposing a behaviour change that is not transparent to end users, and requires them to take action.

The primary benefit of this is that it allows for redistributors to adapt their tooling in time for the new Python version and provides a clear and consistent point for change across the ecosystem. It also puts a clear deadline on when the default behaviour will consistently require a virtual environment by default (once Python 3.12 goes end-of-life).

The primary issue with this approach is that it enforces a behaviour change on users when they upgrade to a new Python version, which can hamper the adoption of a new Python version. However, this is a migration/upgrade for existing users and it is a common expectation that some changes will be needed for migration/upgrades.

The author of this PEP believes that the benefits of applying this consistently throughout the ecosystem with a deadline outweigh the drawbacks of enforcing a best-practice on users when they upgrade.