.\" Automatically generated by Pandoc 2.14.0.2
.\"
.TH "PY" "1" "2021-06-18" "Python Launcher 0.16.1" "Python Launcher"
.hy
.SH NAME
.PP
py - launch a Python interpreter
.SH SYNOPSIS
.PP
\f[B]py\f[R] [\f[B]-[X]/[X.Y]\f[R]] \&...
.SH DESCRIPTION
.PP
\f[B]py\f[R] launches the most appropriate Python interpreter it can
find.
It is meant to act as a shorthand for launching \f[B]python\f[R] without
having to think about \f[I]which\f[R] 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.
.SH SPECIFYING A PYTHON VERSION
.PP
If a command-line option is provided in the form of \f[B]-X\f[R] or
\f[B]-X.Y\f[R] where \f[I]X\f[R] and \f[I]Y\f[R] are integers, then that
version of Python will be launched (if available).
For instance, providing \f[B]-3\f[R] will launch the newest version of
Python 3 while \f[B]-3.6\f[R] will try to launch Python 3.6.
.SH SEARCHING FOR PYTHON INTERPRETERS
.PP
When no command-line arguments are provided to the launcher, what is
deemed the most \[lq]appropriate\[rq] interpreter is searched for as
follows:
.IP "1." 3
An activated virtual environment (launched immediately if available)
.IP "2." 3
A \f[B].venv\f[R] directory in the current working directory or any
parent directory containing a virtual environment (launched immediately
if available)
.IP "3." 3
If a file path is provided as the first argument, look for a shebang
line containing \f[B]/usr/bin/python\f[R],
\f[B]/usr/local/bin/python\f[R], \f[B]/usr/bin/env python\f[R] or
\f[B]python\f[R] and any version specification in the executable name is
treated as a version specifier (like with \f[B]-X\f[R]/\f[B]-X.Y\f[R]
command-line options)
.IP "4." 3
Check for any appropriate environment variable (see
\f[B]ENVIRONMENT\f[R])
.IP "5." 3
Search \f[B]PATH\f[R] for all \f[B]pythonX.Y\f[R] executables
.IP "6." 3
Launch the newest version of Python (while matching any version
restrictions previously specified)
.PP
All unrecognized command-line arguments are passed on to the launched
Python interpreter.
.SH OPTIONS
.TP
\f[B]-h\f[R]/\f[B]\[en]help\f[R]
Print a help message and exit; must be specified on its own.
.TP
\f[B]\[en]list\f[R]
List all known interpreters (except activated virtual environment); must
be specified on its own.
.TP
\f[B]-[X]\f[R]
Launch the latest Python \f[I]X\f[R] version (e.g.\ \f[B]-3\f[R] for the
latest Python 3).
See \f[B]ENVIRONMENT\f[R] for details on the \f[B]PY_VERSION[X]\f[R]
environment variable.
.TP
\f[B]-[X.Y]\f[R]
Launch the specified Python version (e.g.\ \f[B]-3.6\f[R] for Python
3.6).
.SH ENVIRONMENT
.TP
\f[B]PY_PYTHON\f[R]
Specify the version of Python to search for when no Python version is
explicitly requested (must be formatted as `X.Y'; e.g.\ \f[B]3.6\f[R] to
use Python 3.6 by default).
.TP
\f[B]PY_PYTHON[X]\f[R]
Specify the version of Python to search for when only a major version is
specified (must be formatted as `X.Y'; e.g.\ set \f[B]PY_PYTHON3\f[R] to
\f[B]3.6\f[R] to cause \f[B]-3\f[R] to use Python 3.6).
.TP
\f[B]PYLAUNCH_DEBUG\f[R]
Log details to stderr about how the Launcher is operating.
.TP
\f[B]VIRTUAL_ENV\f[R]
Path to a directory containing virtual enviroment to use when no Python
version is explicitly requested; typically set by activating a virtual
environment.
.TP
\f[B]PATH\f[R]
Used to search for Python interpreters.
.SH AUTHORS
.PP
Copyright \[co] 2018 Brett Cannon.
.PP
Licensed under MIT.
.SH HOMEPAGE
.PP
https://github.com/brettcannon/python-launcher/
.SH SEE ALSO
.PP
python(1), python3(1).