From fbff1baf33aa6a5ba8774eed941fe4a808f1efa2 Mon Sep 17 00:00:00 2001 From: Zanie Blue Date: Wed, 31 Jul 2024 09:40:50 -0400 Subject: [PATCH] Improvements to the Python version concepts documentation (#5638) Depends on https://github.com/astral-sh/uv/pull/5637 --- docs/concepts/python-versions.md | 116 ++++++++++++++++++++++++------- 1 file changed, 90 insertions(+), 26 deletions(-) diff --git a/docs/concepts/python-versions.md b/docs/concepts/python-versions.md index caae8310dee0..563c47dc09c4 100644 --- a/docs/concepts/python-versions.md +++ b/docs/concepts/python-versions.md @@ -1,14 +1,26 @@ # Python versions A Python version is composed of a Python interpreter (i.e. the `python` executable), the standard -library, and other supporting files. It is common for an operating system to come with a Python -version installed. +library, and other supporting files. -## Requesting a version +## Managed and system Python installations + +Since it is common for a system to have an existing Python installation, uv supports +[discovering](#discovery-of-python-versions) Python versions. However, uv also supports [installing +Python versions](#installing-a-python-version) 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 will automatically download a Python version if it cannot be found. + 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 -For example, when creating a virtual environment: +A specific Python version can be requested with the `--python` flag in most uv commands. For +example, when creating a virtual environment: ```bash uv venv --python 3.11.6 @@ -17,7 +29,7 @@ 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. -Many Python version request formats are supported: +The following Python version request formats are supported: - `` e.g. `3`, `3.12`, `3.12.3` - `` e.g. `>=3.12,<3.13` @@ -27,12 +39,25 @@ Many Python version request formats are supported: - `` e.g. `cpython>=3.12,<3.13` - `----` e.g. `cpython-3.12.3-macos-aarch64-none` -## Installing a Python version +Additionally, a specific system Python interpreter can be requested with: + +- `` e.g. `/opt/homebrew/bin/python3` +- `` e.g. `mypython3` +- `` e.g. `/some/environment/` -Sometimes it is preferable to install the Python versions before they are needed. +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](#disabling-automatic-python-downloads). + +## 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: ```bash @@ -100,50 +125,89 @@ 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 `PATH` as `python`, `python3`, or `python3.x` on macOS and Linux, or `python.exe` + on Windows. +- On Windows, the Python interpreter returned by `py --list-paths` that 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](#requesting-a-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. However, It's possible to adjust uv's Python version selection -preference with the `python-preference` option. +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 installations -- `installed`: Prefer installed Python installations, only download managed Python installations - if no system Python installation is found -- `managed`: Prefer managed Python installations over system Python installations, even if - fetching is required - `system`: Prefer system Python installations over managed Python installations - `only-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. -## Discovery order +!!! note -When searching for a Python version, the following locations are checked: + Automatic Python version downloads can be [disabled](#disabling-automatic-python-downloads) + without changing the preference. -- Managed Python versions in the `UV_PYTHON_INSTALL_DIR`. -- A Python interpreter on the `PATH` as `python3` on macOS and Linux, or `python.exe` on Windows. -- On Windows, the Python interpreter returned by `py --list-paths` that matches the requested - version. +## 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: -If a specific Python version is requested, e.g. `--python 3.7`, additional executable names are -included in the search: +- CPython: `cpython`, `cp` +- PyPy: `pypy`, `pp` +- GraalPy: `graalpy`, `gp` -- A Python interpreter on the `PATH` as, e.g., `python3.7` on macOS and Linux. +Implementation name requests are not case sensitive. -## Python distributions +See the [Python version request](#requesting-a-version) 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`](https://github.com/indygreg/python-build-standalone) project. The project is partially maintained by the uv maintainers and is used by many other Python projects. -The Python distributions are self-contained and highly-portable. Additionally, these distributions -have various build-time optimizations enabled to ensure they are performant. +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](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation for details. +### PyPy distributions + PyPy distributions are provided by the PyPy project.