Text of peps.python.org › pep-0394 as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 394 – The “python” Command on Unix-Like Systems | peps.python.org

PEP 394 – The “python” Command on Unix-Like Systems PEP 394 – The “python” Command on Unix-Like Systems Author : Kerrick Staley <mail at kerrickstaley.com>, Alyssa Coghlan <ncoghlan at gmail.com>, Barry Warsaw <barry at python.org>, Petr Viktorin <encukou at gmail.com>, Miro Hrončok <miro at hroncok.cz>, Carol Willing <willingc at gmail.com> Status : Active Type : Informational Created : 02-Mar-2011 Post-History : 04-Mar-2011, 20-Jul-2011, 16-Feb-2012, 30-Sep-2014, 28-Apr-2018, 26-Jun-2019 Resolution : Python-Dev message Table of Contents Abstract Recommendation For Python runtime distributors For Python script publishers For end users of Python History of this PEP Current Rationale Future Changes to this Recommendation Migration Notes Backwards Compatibility Application to the CPython Reference Interpreter Impact on PYTHON* Environment Variables Exclusion of MS Windows References Copyright Abstract This PEP outlines the behavior of Python scripts when the python command is invoked.

Depending on a distribution or system configuration, python may or may not be installed. If python is installed its target interpreter may refer to python2 or python3 . End users may be unaware of this inconsistency across Unix-like systems. This PEP’s goal is to reduce user confusion about what python references and what will be the script’s behavior. The recommendations in the next section of this PEP will outline the behavior when: using virtual environments writing cross-platform scripts with shebangs for either python2 or python3 The PEP’s goal is to clarify the behavior for script end users, distribution providers, and script maintainers / authors.

Recommendation Our recommendations are detailed below. We call out any expectations that these recommendations are based upon. For Python runtime distributors We expect Unix-like software distributions (including systems like macOS and Cygwin) to install the python2 command into the default path whenever a version of the Python 2 interpreter is installed, and the same for python3 and the Python 3 interpreter. When invoked, python2 should run some version of the Python 2 interpreter, and python3 should run some version of the Python 3 interpreter.

If the python command is installed, it is expected to invoke either the same version of Python as the python3 command or as the python2 command. Distributors may choose to set the behavior of the python command as follows: python2 , python3 , not provide python command, allow python to be configurable by an end user or a system administrator. The Python 3.x idle , pydoc , and python-config commands should likewise be available as idle3 , pydoc3 , and python3-config ; Python 2.x versions as idle2 , pydoc2 , and python2-config .

The commands with no version number should either invoke the same version of Python as the python command, or not be available at all. When packaging third party Python scripts, distributors are encouraged to change less specific shebangs to more specific ones. This ensures software is used with the latest version of Python available, and it can remove a dependency on Python 2. The details on what specifics to set are left to the distributors; though.

Example specifics could include: Changing python shebangs to python3 when Python 3.x is supported. Changing python shebangs to python2 when Python 3.x is not yet supported. Changing python3 shebangs to python3.8 if the software is built with Python 3.8. When a virtual environment (created by the PEP 405 venv package or a similar tool such as virtualenv or conda ) is active, the python command should refer to the virtual environment’s interpreter and should always be available.

The python3 or python2 command (according to the environment’s interpreter version) should also be available. For Python script publishers When reinvoking the interpreter from a Python script, querying sys.executable to avoid hardcoded assumptions regarding the interpreter location remains the preferred approach. Encourage your end users to use a virtual environment. This makes the user’s environment more predictable (possibly resulting in fewer issues), and helps avoid disrupting their system.

For scripts that are only expected to be run in an activated virtual environment, shebang lines can be written as #!/usr/bin/env python , as this instructs the script to respect the active virtual environment. In cases where the script is expected to be executed outside virtual environments, developers will need to be aware of the following discrepancies across platforms and installation methods: Older Linux distributions will provide a python command that refers to Python 2, and will likely not provide a python2 command.

Some newer Linux distributions will provide a python command that refers to Python 3. Some Linux distributions will not provide a python command at all by default, but will provide a python3 command by default. When potentially targeting these environments, developers may either use a Python package installation tool that rewrites shebang lines for the installed environment, provide instructions on updating shebang lines interactively, or else use more specific shebang lines that are tailored to the target environment.

Scripts targeting both “ old systems ” and systems without the default python command need to make a compromise and document this situation. Avoiding shebangs (via the console_scripts Entry Points ( [9] ) or similar means) is the recommended workaround for this problem. Applications designed exclusively for a specific environment (such as a container or virtual environment) may continue to use the python command name.

For end users of Python While far from being universally available, python remains the preferred spelling for explicitly invoking Python, as this is the spelling that virtual environments make consistently available across different platforms and Python installations. For software that is not distributed with (or developed for) your system, we recommend using a virtual environment, possibly with an environment manager like conda or pipenv , to help avoid disrupting your system Python installation.

These recommendations are the outcome of the relevant python-dev discussions in March and July 2011 ( [1] , [2] ), February 2012 ( [4] ), September 2014 ( [6] ), discussion on GitHub in April 2018 ( [7] ), on python-dev in February 2019 ( [8] ), and during the PEP update review in May/June 2019 ( [10] ). History of this PEP In 2011, the majority of distributions aliased the python command to Python 2, but some started switching it to Python 3 ( [5] ).

As some of the former distributions did not provide a python2 command by default, there was previously no way for Python 2 code (or any code that invokes the Python 2 interpreter directly rather than via sys.executable ) to reliably run on all Unix-like systems without modification, as the python command would invoke the wrong interpreter version on some systems, and the python2 command would fail completely on others.

This PEP originally provided a very simple mechanism to restore cross-platform support, with minimal additional work required on the part of distribution maintainers. Simplified, the recommendation was: The python command was preferred for code compatible with both Python 2 and 3 (since it was available on all systems, even those that already aliased it to Python 3). The python command should always invoke Python 2 (to prevent hard-to-diagnose errors when Python 2 code is run on Python 3).

The python2 and python3 commands should be available to specify the version explicitly. However, these recommendations implicitly assumed that Python 2 would always be available. 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 the python command or switching it to invoke Python 3. Some distributors also decided that

The rest of this page is on the live site.