db371560bc
To enforce the 100 character line limit in markdown files introduced in https://github.com/astral-sh/uv/pull/5635, and to automate the formatting of markdown files, i've added prettier and formatted our markdown files with it. I've excluded the changelog and the generated references documentation from this for having too many changes, but we can also include them. I'm not particular on which style we use. My main motivations are (major) not having to reflow markdown files myself anymore and (minor) consistence between all markdown files. I've chosen prettier for similar reason as we chose black, it's a single good style that's automated and shared in the community. I do prefer prettier's style of not breaking inside of a link name though. This PR is in two parts, the first adds prettier to CI and documents using it, while the second actually formats the docs. When merge conflicts arise, we can drop the last commit and regenerate it with `npx prettier --prose-wrap always --write BENCHMARKS.md CONTRIBUTING.md README.md STYLE.md docs/*.md docs/concepts/**/*.md docs/guides/**/*.md docs/pip/**/*.md`. --------- Co-authored-by: Zanie Blue <contact@zanie.dev>
7.3 KiB
Python versions
A Python version is composed of a Python interpreter (i.e. the python executable), the standard
library, and other supporting files.
Managed and system Python installations
Since it is common for a system to have an existing Python installation, uv supports discovering Python versions. However, uv also supports installing Python versions itself. To distinguish between these two types of Python installations, uv refers to Python versions it installs as managed Python installations and all other Python installations as system Python installations.
!!! note
uv does not distinguish between Python versions installed by the operating system vs those
installed and managed by other tools. For example, if a Python installation is managed with
`pyenv`, it would still be considered a _system_ Python version in uv.
Requesting a version
A specific Python version can be requested with the --python flag in most uv commands. For
example, when creating a virtual environment:
uv venv --python 3.11.6
uv will ensure that Python 3.11.6 is available — downloading and installing it if necessary — then create the virtual environment with it.
The following Python version request formats are supported:
<version>e.g.3,3.12,3.12.3<version-specifier>e.g.>=3.12,<3.13<implementation>e.g.cpythonorcp<implementation>@<version>e.g.cpython@3.12<implementation><version>e.g.cpython3.12orcp312<implementation><version-specifier>e.g.cpython>=3.12,<3.13<implementation>-<version>-<os>-<arch>-<libc>e.g.cpython-3.12.3-macos-aarch64-none
Additionally, a specific system Python interpreter can be requested with:
<executable-path>e.g./opt/homebrew/bin/python3<executable-name>e.g.mypython3<install-dir>e.g./some/environment/
By default, uv will automatically download Python versions if they cannot be found on the system.
This behavior can be
disabled with the python-fetch option.
Installing a Python version
uv bundles a list of downloadable CPython and PyPy distributions for macOS, Linux, and Windows.
!!! tip
By default, Python versions are automatically downloaded as needed without using
`uv python install`.
To install a Python version at a specific version:
uv python install 3.12.3
To install the latest patch version:
uv python install 3.12
To install a version that satisfies constraints:
uv python install '>=3.8,<3.10'
To install multiple versions:
uv python install 3.9 3.10 3.11
Project Python versions
By default uv python install will verify that a managed Python version is installed or install the
latest version.
However, a project may define a .python-version file specifying the default Python version to be
used. If present, uv will install the Python version listed in the file.
Alternatively, a project that requires multiple Python versions may also define a .python-versions
file. If present, uv will install all of the Python versions listed in the file. This file takes
precedence over the .python-version file.
uv will also respect Python requirements defined in a pyproject.toml file during project command
invocations.
Viewing available Python versions
To list installed and available Python versions:
uv python list
By default, downloads for other platforms and old patch versions are hidden.
To view all versions:
uv python list --all-versions
To view Python versions for other platforms:
uv python list --all-platforms
To exclude downloads and only show installed Python versions:
uv python list --only-installed
Discovery of Python versions
When searching for a Python version, the following locations are checked:
- Managed Python installations in the
UV_PYTHON_INSTALL_DIR. - A Python interpreter on the
PATHaspython,python3, orpython3.xon macOS and Linux, orpython.exeon Windows. - On Windows, the Python interpreter returned by
py --list-pathsthat matches the requested version.
When performing discovery, non-executable files will be ignored. Each discovered executable is queried for metadata to ensure it meets the requested Python version. If the query fails, the executable will be skipped.
If a Python version cannot be found on the system, uv will check for a compatible managed Python version download.
Disabling automatic Python downloads
By default, uv will automatically download Python versions when needed.
The python-fetch option can be used to disable this behavior. By default, it is set to
automatic; set to manual to only allow Python downloads during uv python install.
Adjusting Python version preferences
By default, uv will attempt to use Python versions found on the system and only download managed interpreters when necessary.
The python-preference option can be used to adjust this behavior. By default, it is set to
managed which prefers managed Python installations over system Python installations. However,
system Python installations are still preferred over downloading a managed Python version.
The following alternative options are available:
only-managed: Only use managed Python installations; never use system Python installationssystem: Prefer system Python installations over managed Python installationsonly-system: Only use system Python installations; never use managed Python installations
These options allow disabling uv's managed Python versions entirely or always using them and ignoring any existing system installations.
!!! note
Automatic Python version downloads can be [disabled](#disabling-automatic-python-downloads)
without changing the preference.
Python implementation support
uv supports the CPython, PyPy, and GraalPy Python implementations. If a Python implementation is not supported, uv will fail to discover its interpreter.
The implementations may be requested with either the long or short name:
- CPython:
cpython,cp - PyPy:
pypy,pp - GraalPy:
graalpy,gp
Implementation name requests are not case sensitive.
See the Python version request documentation for more details on the supported formats.
Managed Python distributions
uv supports downloading and installing CPython and PyPy distributions.
CPython distributions
Python does not publish official distributable CPython binaries, uv uses third-party standalone
distributions from the
python-build-standalone project. The
project is partially maintained by the uv maintainers and is used by many other Python projects.
The uv Python distributions are self-contained, highly-portable, and performant. While Python can be
built from source, as in tools like pyenv, it requires preinstalled system dependencies and
creating optimized, performant builds is very slow.
These distributions have some behavior quirks, generally as a consequence of portability. See the
python-build-standalone quirks
documentation for details.
PyPy distributions
PyPy distributions are provided by the PyPy project.