8000 PEP 704: Require virtual environments by default for installers · python/peps@456218d · GitHub
[go: up one dir, main page]
Skip to content

Commit 456218d

Browse files
pradyunsgpradyunsg
committed
PEP 704: Require virtual environments by default for installers
Enforce the use of virtual environments and establish a conventional name for the virtual environment directory.
1 parent 2411637 commit 456218d

File tree

1 file changed

+137
-0
lines changed

1 file changed

+137
-0
lines changed

‎pep-0704.rst

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
PEP: 704
2+
Title: Require virtual environments by default for installers
3+
Author: Pradyun Gedam <pradyunsg@gmail.com>
4+
Sponsor: Brett Cannon <brett@python.org>
5+
PEP-Delegate: Paul Moore <p.f.moore@gmail.com>
6+
Discussions-To: https://discuss.python.org/t/22846
7+
Status: Draft
8+
Type: Standards Track
9+
Topic: Packaging
10+
Content-Type: text/x-rst
11+
Created: 16-Jan-2023
12+
Python-Version: 3.13
13+
Post-History: 16-Jan-2023
14+
15+
16+
Abstract
17+
========
18+
19+
This PEP proposes that package installers like ``pip`` MUST require a virtual environment by default, on Python 3.13+.
20+
21+
Motivation
22+
==========
23+
24+
Python virtual environments are an essential part of the development workflow for Python. However, it requires extra effort since it is an opt-in feature, and requires users to either:
25+
26+
- take explicit steps to activate/deactivate a virtual environment
27+
- use ``<path-to-venv>/<bin-path>/<executable>`` to run files
28+
29+
This creates a barrier to entry for many new users, since virtual environments serve as a pre-requisite for typical Python development workflows and how virtual environments work is a lot of information for anyone new. It can take a lot of extra time and effort to explain them.
30+
31+
Further, activation of virtual environment uses a slightly different syntax/mechanism to activate on different platforms.
32+
33+
It also creates a scope for mistakes, since users must remember to activate the virtual environment before running an installer like ``pip``. On certain Linux distributions, this can result in the installer modifying files that are owned by the operating system (this is partially mitigated by :pep:`668` for distributions that opt-in to marking their environments accordingly).
34+
35+
This PEP proposes that the default behaviour of installers like ``pip`` should be to require a virtual environment to be active. This would make it easier for new users to get started with Python, and would reduce the scope for mistakes.
36+
37+
38+
Specification
39+
=============
40+
41+
When a user runs an installer without an active virtual environment, the installer MUST print an error message and exit with a non-zero exit code. The error message MUST 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.
42+
43+
The installer MUST also provide an command line option to disable this behaviour, allowing a user to opt-in to running the tool outside of a virtual environment. The installer MAY include this in the error message that it prints, and MUST include it in the documentation page it links to.
44+
45+
If the installer includes a link to a documentation page in the error message described above, the documentation page SHOULD be written with a focus on new users. It should explain what virtual environments are, why they are required, and how to create and activate a virtual environment. It SHOULD include instructions for the most common shells and platforms.
46+
47+
Installers MAY choose to implement this default behaviour on any Python versions, but MUST implement it on Python 3.13 or newer.
48+
49+
50+
Backwards Compatibility
51+
=======================
52+
53+
This PEP is backwards incompatible with workflows where users who are using installers outside of virtual environments. Such users will be prompted with an error message and will need to either:
54+
55+
- explicitly opt-in to running the installer outside of a virtual environment, or
56+
- create and use a virtual environment
57+
58+
Users who are already using virtual environments will not be affected by this change.
59+
60+
Workflow tools (which manage virtual environments for the user, under the hood) should be unaffected, since they should already be using the virtual environment for running the installer.
61+
62+
63+
Security Implications
64+
=====================
65+
66+
This PEP does not introduce any new security implications.
67+
68+
69+
How to Teach This
70+
=================
71+
72+
This PEP does require 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``.[1]_
73+
74+
75+
Reference Implementation
76+
========================
77+
78+
There is no reference implementation for this PEP, however the proposed behaviour is already implemented in ``pip`` and can be achieved by setting ``PIP_REQUIRE_VENV`` environment variable to ``1`` (not setting it would result in the proposed opt-in behaviour).
79+
80+
Rejected Ideas
81+
==============
82+
83+
Do not specify a name for the virtual environment directory
84+
-----------------------------------------------------------
85+
86+
Using a consistent name for the virtual environment directory is important for a few reasons:
87+
88+
1. It makes it easier for users to find the virtual environment directory, and to activate it.
89+
2. It removes a decision point for new users, since they do not need to decide on a name for the virtual environment directory.
90+
3. It creates a clear convention within the ecosystem, which makes it easier for users to find documentation.
91+
4. It ensures consistency across different tools, so that differences in the error message of different tools do not confuse users.
92+
93+
Use a different name for the virtual environment directory
94+
----------------------------------------------------------
95+
96+
Functionally, the directory name does not matter much as long as there is a single consistent suggestion.
97+
98+
The name ``.venv`` was picked since it:
99+
100+
1. does not conflict with any valid Python import name
101+
2. does not conflict ``venv`` module in the standard library
102+
3. has pre-existing usage in the Python community
103+
4. has support for auto-detection in common text editors
104+
5. can be typed without modifier keys on common keyboard layouts
105+
106+
Do not couple tooling behaviour with a Python version
107+
-----------------------------------------------------
108+
109+
This PEP creates a coupling between the behaviour of installers and the Python version, enforcing a behaviour change in installers based on a Python version.
110+
111+
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.
112+
113+
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.
114+
115+
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).
116+
117+
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 e 629A xpectation that _some_ changes to be needed for migration/upgrades.
118+
119+
The author of this PEP believes that enforcing 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.
120+
121+
122+
Open Issues
123+
===========
124+
125+
None.
126+
127+
128+
Footnotes
129+
=========
130+
131+
.. [1] https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments
132+
133+
Copyright
134+
=========
135+
136+
This document is placed in the public domain or under the
137+
CC0-1.0-Universal license, whichever is more permissive.

0 commit comments

Comments
 (0)
0