diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 7abbe0ea4..87c1226b3 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -18,7 +18,7 @@ - [Projects](preview/projects.md) - [Command-line tools](preview/tools.md) -- [Python toolchains](preview/toolchains.md) +- [Python versions](python-versions.md) - [Workspaces](preview/workspaces.md) - [Dependency sources](preview/dependencies.md) - [Resolution](resolution.md) diff --git a/docs/guides/install-python.md b/docs/guides/install-python.md index 3e1e4bb04..9c7248c8d 100644 --- a/docs/guides/install-python.md +++ b/docs/guides/install-python.md @@ -26,7 +26,7 @@ To install a specific Python version: $ uv python install 3.12 ``` -See the [Python toolchain](../preview/toolchains.md) documentation for more details. +See the [Python versions](../python-versions.md) documentation for more details. ## Viewing Python installations diff --git a/docs/preview/toolchains.md b/docs/python-versions.md similarity index 50% rename from docs/preview/toolchains.md rename to docs/python-versions.md index 602181cc3..fcf4b12ce 100644 --- a/docs/preview/toolchains.md +++ b/docs/python-versions.md @@ -1,12 +1,12 @@ **Warning: This documentation refers to experimental features that may change.** -# Toolchains +# Python versions -A Python toolchain 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 toolchain installed and there are many tools to help manage Python toolchains. +A Python installation 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 and there are many tools to help manage Python versions. -## Requesting a toolchain +## Requesting a version -uv will automatically download a toolchain if it cannot be found. +uv will automatically download a Python version if it cannot be found. In stable commands, this behavior requires enabling preview mode. For example, when creating a virtual environment: @@ -22,7 +22,7 @@ For commands that are in preview, like `uv sync`, preview behavior is always on. uv sync --python 3.12.3 ``` -Many toolchain request formats are supported: +Many Python version request formats are supported: - `` e.g. `3`, `3.12`, `3.12.3` - `` e.g. `>=3.12,<3.13` @@ -34,11 +34,11 @@ Many toolchain request formats are supported: At this time, only CPython downloads are supported. However, PyPy support is planned. -## Installing a toolchain +## Installing a Python version -Sometimes it is preferable to install the toolchains before they are needed. +Sometimes it is preferable to install the Python versions before they are needed. -To install a toolchain at a specific version: +To install a Python version at a specific version: ```bash uv python install 3.12.3 @@ -62,21 +62,21 @@ To install multiple versions: uv python install 3.9 3.10 3.11 ``` -## Installing project toolchains +## Project Python versions -By default `uv python install` will verify that a managed toolchain is installed or install the latest version. +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 toolchain to be used. If present, -uv will install the toolchain listed in the file. +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 toolchains listed in the file. This file takes precedence over the `.python-version` file. +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 toolchains +## Viewing available Python versions -To list installed and available toolchains: +To list installed and available Python versions: ```bash uv python list @@ -90,37 +90,36 @@ To view all versions: uv python list --all-versions ``` -To view toolchains for other platforms: +To view Python versions for other platforms: ```bash uv python list --all-platforms ``` -To exclude downloads and only show installed toolchains: +To exclude downloads and only show installed Python versions: ```bash uv python list --only-installed ``` -## Adjusting toolchain preferences +## Adjusting Python version preferences -By default, uv will attempt to use Python toolchains found on the system and only download managed interpreters when necessary. -However, It's possible to adjust uv's toolchain selection preference with the `toolchain-preference` option. +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. -- `only-managed`: Only use managed toolchains, never use system toolchains. -- `prefer-installed-managed`: Prefer installed managed toolchains, but use system toolchains if not found. If neither can be - found, download a managed interpreter. -- `prefer-managed`: Prefer managed toolchains, even if one needs to be downloaded, but use system toolchains if found. -- `prefer-system`: Prefer system toolchains, only use managed toolchains if no system interpreter is found. -- `only-system`: Only use system toolchains, never use managed toolchains. +- `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 toolchains entirely or always using them and ignoring any existing system installations. +These options allow disabling uv's managed Python versions entirely or always using them and ignoring any existing system installations. ## Discovery order -When searching for a toolchain, the following locations are checked: +When searching for a Python version, the following locations are checked: -- Managed toolchains in the `UV_PYTHON_INSTALL_DIR`. +- 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.