Abstract

This PEP recommends that package installers like pip require a virtual environment by default on Python 3.13+.

PEP Withdrawal

During discussion of this PEP, it became clear that changes to pip’s UX are not controlled by PEPs as proposed. It also became clear that a significant number of users rely on being able to mix managed-by-pip dependencies with managed-by-some-other-tool dependencies (most prominently, when using Conda).

Further, a significant subset of the benefits of the proposed change are achievable via PEP 668 (accepted and implemented at the time of writing). It provides redistributors of the Python interpreter control over whether users should be required to use a virtual environment, what the messaging presented to the user is and how the rollout of that change should happen for their users.

Since enforcement of virtual environments with pip was the primary focus of this PEP, it felt more appropriate to withdraw this PEP than to refocus it on a different topic.

A future PEP to resolve the virtual environment naming convention question/issues would still be appropriate, but it’s worth starting any such effort as a fresh PEP focused on the benefits of such a convention, rather than on the enforcement of it.

Motivation

Python virtual environments are an essential part of the development workflow for Python. However, they require extra effort since they are an opt-in feature, and requires users to either:

• take explicit steps to activate/deactivate a virtual environment
• use <path-to-venv>/<bin-path>/<executable> to run files

For new users, things will seemingly work correctly when virtual environments are not used -— until they don’t. Further, activating a virtual environment uses slightly different syntax and mechanisms on different platforms. This complicates the introduction to virtual environments, since now information and context about how/why they are useful needs to explained to justify adding additional steps to the workflow.

It also creates a scope for mistakes, since users need to remember to activate the virtual environment before running an installer like pip or configure those installers to error out. On certain Linux distributions, forgetting to do so can result in the installer modifying files that are owned by the operating system (which is partially mitigated by PEP 668 for distributions that opt-in to marking their environments accordingly).

Rationale

Changing the default behaviour of installers like pip to require a virtual environment to be active would:

• make it easier for new users to get started with Python (since there’s a consistent experience and virtual environments are understood as a thing you’re required to use)
• reduce the scope for accidental installation issues for all users by default (by explicitly flagging when you’re not using a virtual environment).

Setting up a convention of placing the virtual environment in-tree in a directory named .venv removes a decision point for common workflows and creates a clear convention within the ecosystem.

Specification

Backwards Compatibility

This PEP is backwards incompatible with workflows where users are using installers outside of virtual environments. Such users will be prompted with an error message and will need to either:

• explicitly opt-in to running the installer outside of a virtual environment, or
• create and use a virtual environment

Users who are already using virtual environments will not be affected by this change.

Workflow tools (which manage virtual environments for the user, under the hood) should be unaffected, since they should already be using a virtual environment for running the installer.

Security Implications

This PEP does not introduce any new security implications.

How to Teach This

This PEP requires that new users create and use a virtual environment to get started with using Python packages. This is, however, a best practice, as demonstrated by the section on “basics of how to install Python packages” in the Python Packaging User Guide, which explains how/what virtual environments are before discussing using pip.

Reference Implementation

There is no reference implementation for this PEP. However, the proposed behaviour is largely already implemented in pip and can be activated by setting the PIP_REQUIRE_VENV environment variable to 1. (Leaving it unset results in the proposed opt-in behaviour of not requiring a virtual environment for installation.)

Implementation Notes

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

Rejected Ideas

Open Issues

None.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.