.\" Automatically generated by Pandoc 3.2.1
.\"
.TH "PY" "1" "2024-06-30" "Python Launcher 1.0.1" "Python Launcher"
.SH NAME
py \- launch a Python interpreter
.SH SYNOPSIS
\f[B]py\f[R] [\f[B]\-[X]/[X.Y]\f[R]] \&...
.SH DESCRIPTION
\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
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
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]\-\-help\f[R]
Print a help message and exit; must be specified on its own.
.TP
\f[B]\-\-list\f[R]
List all known interpreters (except virtual environments); 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 environment 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
Copyright © 2018 Brett Cannon.
.PP
Licensed under MIT.
.SH HOMEPAGE
https://github.com/brettcannon/python\-launcher/
.SH SEE ALSO
python(1), python3(1).