You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pep-0704.rst
+36-10Lines changed: 36 additions & 10 deletions
Original file line number
Diff line number
Diff line change
@@ -44,11 +44,22 @@ Setting up a convention of placing the virtual environment in-tree in a director
44
44
Specification
45
45
=============
46
46
47
-
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.
47
+
Requiring a virtual environment by default
48
+
------------------------------------------
48
49
49
-
The installer SHOULD also provide a mechanism 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 SHOULD include it in the documentation page it links to.
50
+
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.
50
51
51
-
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.
52
+
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.
53
+
54
+
See `Implementation notes`_ for more details.
55
+
56
+
Opting out of virtual environments
57
+
----------------------------------
58
+
59
+
The installer SHOULD also provide a explicit opt-in before 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.
60
+
61
+
Consistent timeline for the change
62
+
----------------------------------
52
63
53
64
Installers MAY choose to implement this default behaviour on any Python versions, but SHOULD implement it on Python 3.13 or newer.
54
65
@@ -75,14 +86,34 @@ This PEP does not introduce any new security implications.
75
86
How to Teach This
76
87
=================
77
88
78
-
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]_
89
+
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 <https://packaging.python.org/en/latest/tutorials/installing-packages/#creating-virtual-environments>`__ 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``.
79
90
80
91
81
92
Reference Implementation
82
93
========================
83
94
84
-
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).
95
+
There is no reference implementation for this PEP, however the proposed behaviour is largely 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).
96
+
97
+
98
+
Implementation Notes
99
+
====================
100
+
101
+
Detecting an active virtual environment
102
+
---------------------------------------
103
+
104
+
:pep:`As discussed in PEP 668 <668#backwards-compatibility>`, the logic for robustly detecting a virtual environment is something like::
85
105
106
+
def is_virtual_environment():
107
+
return sys.base_prefix != sys.prefix or hasattr(sys, "real_prefix")
108
+
109
+
Documentation on using a virtual environment
110
+
--------------------------------------------
111
+
112
+
Package installers are expected to provide a link to a documentation page in the error message.
113
+
114
+
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.
115
+
116
+
Such a documentation page should be made available in the `Python Packaging User Guide <https://packaging.python.org>`__ to reduce duplicated effort across installers for covering this topic.
0 commit comments