|
| 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