py - Man Page

launch a Python interpreter


py [-[X]/[X.Y]] ...


py launches the most appropriate Python interpreter it can find. It is meant to act as a shorthand for launching python without having to think about which Python interpreter is the most desired. The Python Launcher is not meant to substitute all ways of launching Python, e.g. if a specific Python interpreter is desired then it is assumed it will be directly executed.

Specifying a Python Version

If a command-line option is provided in the form of -X or -X.Y where X and Y are integers, then that version of Python will be launched (if available). For instance, providing -3 will launch the newest version of Python 3 while -3.6 will try to launch Python 3.6.

Searching for Python Interpreters

When no command-line arguments are provided to the launcher, what is deemed the most “appropriate” interpreter is searched for as follows:

  1. An activated virtual environment (launched immediately if available)
  2. A .venv directory in the current working directory or any parent directory containing a virtual environment (launched immediately if available)
  3. If a file path is provided as the first argument, look for a shebang line containing /usr/bin/python, /usr/local/bin/python, /usr/bin/env python or python and any version specification in the executable name is treated as a version specifier (like with -X/-X.Y command-line options)
  4. Check for any appropriate environment variable (see Environment)
  5. Search PATH for all pythonX.Y executables
  6. Launch the newest version of Python (while matching any version restrictions previously specified)

All unrecognized command-line arguments are passed on to the launched Python interpreter.



Print a help message and exit; must be specified on its own.


List all known interpreters (except activated virtual environment); must be specified on its own.


Launch the latest Python X version (e.g. -3 for the latest Python 3). See Environment for details on the PY_VERSION[X] environment variable.


Launch the specified Python version (e.g. -3.6 for Python 3.6).



Specify the version of Python to search for when no Python version is explicitly requested (must be formatted as `X.Y'; e.g. 3.6 to use Python 3.6 by default).


Specify the version of Python to search for when only a major version is specified (must be formatted as `X.Y'; e.g. set PY_PYTHON3 to 3.6 to cause -3 to use Python 3.6).


Log details to stderr about how the Launcher is operating.


Path to a directory containing virtual enviroment to use when no Python version is explicitly requested; typically set by activating a virtual environment.


Used to search for Python interpreters.


Copyright © 2018 Brett Cannon.

Licensed under MIT.


See Also

python(1), python3(1).

Referenced By


2021-06-18 Python Launcher 0.16.1