Abstract

This PEP outlines the behavior of Python scripts when thepython commandis invoked.Depending on a distribution or system configuration,python may or may not be installed.Ifpython is installed its target interpreter may refer topython2orpython3.End users may be unaware of this inconsistency across Unix-like systems.This PEP’s goal is to reduce user confusion about whatpython referencesand what will be the script’s behavior.

The recommendations in the next section of this PEP will outline the behaviorwhen:

• using virtual environments
• writing cross-platform scripts with shebangs for eitherpython2 orpython3

The PEP’s goal is to clarify the behavior for script end users, distributionproviders, and script maintainers / authors.

Recommendation

Our recommendations are detailed below.We call out any expectations that these recommendations are based upon.

History of this PEP

In 2011, the majority of distributionsaliased thepython command to Python 2, but some started switching it toPython 3 ([5]). As some of the former distributions did not provide apython2 command by default, there was previously no way for Python 2 code(or any code that invokes the Python 2 interpreter directly rather than viasys.executable) to reliably run on all Unix-like systems withoutmodification, as thepython command would invoke the wrong interpreterversion on some systems, and thepython2 command would fail completelyon others. This PEP originally provided a very simple mechanismto restore cross-platform support, with minimal additional work requiredon the part of distribution maintainers. Simplified, the recommendation was:

1. Thepython command was preferred for code compatible with bothPython 2 and 3 (since it was available on all systems, even those thatalready aliased it to Python 3).
2. Thepython command should always invoke Python 2 (to preventhard-to-diagnose errors when Python 2 code is run on Python 3).
3. Thepython2 andpython3 commands should be available to specifythe version explicitly.

However, these recommendations implicitly assumed that Python 2 would always beavailable. As Python 2 is nearing its end of life in 2020 (PEP 373,PEP 404),distributions are making Python 2 optional or removing it entirely.This means either removing thepython command or switching it to invokePython 3. Some distributors also decided that their users were better served byignoring the PEP’s original recommendations, and provided systemadministrators with the freedom to configure their systems based onthe needs of their particular environment.

Current Rationale

As of 2019, activating a Python virtual environment (or its functionalequivalent) prior to script execution is one way to obtain a consistentcross-platform and cross-distribution experience.

Accordingly, publishers can expect users of the software to provide a suitableexecution environment.

Future Changes to this Recommendation

This recommendation will be periodically reviewed over the next few years,and updated when the core development team judges it appropriate. As apoint of reference, regular maintenance releases for the Python 2.7 serieswill continue until January 2020.

Migration Notes

This section does not contain any official recommendations from the coreCPython developers. It’s merely a collection of notes regarding variousaspects of migrating to Python 3 as the default version of Python for asystem. They will hopefully be helpful to any distributions consideringmaking such a change.

• The main barrier to a distribution switching thepython command frompython2 topython3 isn’t breakage within the distribution, butinstead breakage of private third party scripts developed by sysadminsand other users. Updating thepython command to invokepython3by default indicates that a distribution is willing to break such scriptswith errors that are potentially quite confusing for users that aren’tfamiliar with the backwards incompatible changes in Python 3. Forexample, while the change ofprint from a statement to a builtinfunction is relatively simple for automated converters to handle, theSyntaxError from attempting to use the Python 2 notation in Python 3may be confusing for users that are not aware of the change:

  $ python3 -c 'print "Hello, world!"'  File"<string>", line1print"Hello, world!"^SyntaxError:Missing parentheses in call to 'print'. Did you mean print("Hello, world!")?

  While this might be obvious for experienced Pythonistas, such scriptsmight even be run by people who are not familiar with Python at all.Avoiding breakage of such third party scripts was the key reason thisPEP used to recommend thatpython continue to refer topython2.

• The error messagepython:commandnotfound tends to be surprisinglyactionable, even for people unfamiliar with Python.
• ThepythonX.X (e.g.python3.6) commands exist on modern systems, onwhich they invoke specific minor versions of the Python interpreter. Itcan be useful for distribution-specific packages to take advantage of theseutilities if they exist, since it will prevent code breakage if the defaultminor version of a given major version is changed. However, scriptsintending to be cross-platform should not rely on the presence of theseutilities, but rather should be tested on several recent minor versions ofthe target major version, compensating, if necessary, for the smalldifferences that exist between minor versions. This prevents the need forsysadmins to install many very similar versions of the interpreter.
• When thepythonX.X binaries are provided by a distribution, thepython2 andpython3 commands should refer to one of those filesrather than being provided as a separate binary file.
• It is strongly encouraged that distribution-specific packages usepython3(orpython2) rather thanpython, even in code that is not intended tooperate on other distributions. This will reduce problems if thedistribution later decides to change the version of the Python interpreterthat thepython command invokes, or if a sysadmin installs a custompython command with a different major version than the distributiondefault.
• If the above point is adhered to and sysadmins are permitted to change thepython command, then thepython command should always be implementedas a link to the interpreter binary (or a link to a link) and not viceversa. That way, if a sysadmin does decide to replace the installedpython file, they can do so without inadvertently deleting thepreviously installed binary.
• Even as the Python 2 interpreter becomes less common, it remains reasonablefor scripts to continue to use thepython3 convention, rather than justpython.
• If these conventions are adhered to, it will become the case that thepython command is only executed in an interactive manner as a userconvenience, or else when using a virtual environment or similar mechanism.

Backwards Compatibility

A potential problem can arise if a script adhering to thepython2/python3 convention is executed on a system not supportingthese commands. This is mostly a non-issue, since the sysadmin can simplycreate these symbolic links and avoid further problems. It is a significantlymore obvious breakage than the sometimes cryptic errors that can arise whenattempting to execute a script containing Python 2 specific syntax with aPython 3 interpreter or vice versa.

Application to the CPython Reference Interpreter

While technically a new feature, themakeinstall andmakebininstallcommand in the 2.7 version of CPython were adjusted to create thefollowing chains of symbolic links in the relevantbin directory (thefinal item listed in the chain is the actual installed binary, precedingitems are relative symbolic links):

python -> python2 -> python2.7python-config -> python2-config -> python2.7-config

Similar adjustments were made to the macOS binary installer.

This feature first appeared in the default installation process inCPython 2.7.3.

The installation commands in the CPython 3.x series already create theappropriate symlinks. For example, CPython 3.2 creates:

python3 -> python3.2idle3 -> idle3.2pydoc3 -> pydoc3.2python3-config -> python3.2-config

And CPython 3.3 creates:

python3 -> python3.3idle3 -> idle3.3pydoc3 -> pydoc3.3python3-config -> python3.3-configpysetup3 -> pysetup3.3

The implementation progress of these features in the default installers wasmanaged on the tracker as issue #12627 ([3]).

Impact on PYTHON* Environment Variables

The choice of target for thepython command implicitly affects adistribution’s expected interpretation of the various Python relatedenvironment variables. The use of*.pth files in the relevantsite-packages folder, the “per-user site packages” feature (seepython-msite) or more flexible tools such asvirtualenv are all moretolerant of the presence of multiple versions of Python on a system than thedirect use ofPYTHONPATH.

Exclusion of MS Windows

This PEP deliberately excludes any proposals relating to Microsoft Windows, asdevising an equivalent solution for Windows was deemed too complex to handlehere.PEP 397 and the related discussion on the python-dev mailing listaddress this issue.

References

Copyright

This document has been placed in the public domain.