mirrors/uv
1
0
Fork 0
mirror of https://github.com/astral-sh/uv.git synced 2025-07-07 21:35:00 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Update "Python versions" documentation (#4943)

Browse source 
Replacing references to toolchains
This commit is contained in:
Zanie Blue 2024-07-09 21:07:27 -04:00 • committed by GitHub
parent e01022d75b
commit 5b6dffe522
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 30 additions and 31 deletions
Download patch file Download diff file Expand all files Collapse all files

2
docs/SUMMARY.md
View file

@ -18,7 +18,7 @@
- [Projects](preview/projects.md) - [Projects](preview/projects.md)
- [Command-line tools](preview/tools.md) - [Command-line tools](preview/tools.md)
- [Python toolchains](preview/toolchains.md) - [Python versions](python-versions.md)
- [Workspaces](preview/workspaces.md) - [Workspaces](preview/workspaces.md)
- [Dependency sources](preview/dependencies.md) - [Dependency sources](preview/dependencies.md)
- [Resolution](resolution.md) - [Resolution](resolution.md)

2
docs/guides/install-python.md
View file

@ -26,7 +26,7 @@ To install a specific Python version:
$ uv python install 3.12 $ 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 ## Viewing Python installations

57
docs/preview/toolchains.md → docs/python-versions.md
View file

@ -1,12 +1,12 @@
**Warning: This documentation refers to experimental features that may change.** **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: 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 uv sync --python 3.12.3
``` ```
Many toolchain request formats are supported: Many Python version request formats are supported:
- `<version>` e.g. `3`, `3.12`, `3.12.3` - `<version>` e.g. `3`, `3.12`, `3.12.3`
- `<version-specifier>` e.g. `>=3.12,<3.13` - `<version-specifier>` 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. 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 ```bash
uv python install 3.12.3 uv python install 3.12.3
@ -62,21 +62,21 @@ To install multiple versions:
uv python install 3.9 3.10 3.11 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, However, a project may define a `.python-version` file specifying the default Python version to be used. If present,
uv will install the toolchain listed in the file. 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, 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. 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 ```bash
uv python list uv python list
@ -90,37 +90,36 @@ To view all versions:
uv python list --all-versions uv python list --all-versions
``` ```
To view toolchains for other platforms: To view Python versions for other platforms:
```bash ```bash
uv python list --all-platforms uv python list --all-platforms
``` ```
To exclude downloads and only show installed toolchains: To exclude downloads and only show installed Python versions:
```bash ```bash
uv python list --only-installed 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. 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 toolchain selection preference with the `toolchain-preference` option. 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. - `only-managed`: Only use managed Python installations; never use system Python installations
- `prefer-installed-managed`: Prefer installed managed toolchains, but use system toolchains if not found. If neither can be - `installed`: Prefer installed Python installations, only download managed Python installations if no system Python installation is found
found, download a managed interpreter. - `managed`: Prefer managed Python installations over system Python installations, even if fetching is required
- `prefer-managed`: Prefer managed toolchains, even if one needs to be downloaded, but use system toolchains if found. - `system`: Prefer system Python installations over managed Python installations
- `prefer-system`: Prefer system toolchains, only use managed toolchains if no system interpreter is found. - `only-system`: Only use system Python installations; never use managed Python installations
- `only-system`: Only use system toolchains, never use managed toolchains.
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 ## 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. - 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 - On Windows, the Python interpreter returned by `py --list-paths` that matches the requested
version. version.