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

Add uv python install --preview to the documentation (#10010)

Browse source
This commit is contained in:
Zanie Blue 2024-12-19 16:07:46 -06:00 • committed by GitHub
parent 2b0f8ffdee
commit 8908e26de7
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 43 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

39
docs/concepts/python-versions.md
View file

@ -110,6 +110,45 @@ latest version. If a `.python-version` file is present, uv will install the Pyth
the file. A project that requires multiple Python versions may define a `.python-versions` file. If
present, uv will install all of the Python versions listed in the file.
### Installing Python executables
!!! important
Support for installing Python executables is in _preview_, this means the behavior is experimental
and subject to change.
To install Python executables into your `PATH`, provide the `--preview` option:
```console
$ uv python install 3.12 --preview
```
This will install a Python executable for the requested version into `~/.local/bin`, e.g., as
`python3.12`.
!!! tip
If `~/.local/bin` is not in your `PATH`, you can add it with `uv tool update-shell`.
To install `python` and `python3` executables, include the `--default` option:
```console
$ uv python install 3.12 --default --preview
```
When installing Python executables, uv will only overwrite an existing executable if it is managed
by uv — e.g., if `~/.local/bin/python3.12` exists already uv will not overwrite it without the
`--force` flag.
uv will update executables that it manages. However, it will prefer the latest patch version of each
Python minor version by default. For example:
```console
$ uv python install 3.12.7 --preview # Adds `python3.12` to `~/.local/bin`
$ uv python install 3.12.6 --preview # Does not update `python3.12`
$ uv python install 3.12.8 --preview # Updates `python3.12` to point to 3.12.8
```
## Project Python versions
uv will respect Python requirements defined in `requires-python` in the `pyproject.toml` file during

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

@ -25,24 +25,15 @@ system. If you've previously installed Python with uv, a new version will not be
Python does not publish official distributable binaries. As such, uv uses distributions from Astral [`python-build-standalone`](https://github.com/astral-sh/python-build-standalone) project. See the [Python distributions](../concepts/python-versions.md#managed-python-distributions) documentation for more details.
<!-- TODO(zanieb): Restore when Python shim management is added
Note that when an automatic Python installation occurs, the `python` command will not be added to the shell. Use `uv python install-shim` to ensure the `python` shim is installed.
Once Python is installed, it can be invoked via `python`:
```console
$ python --version
```
To prevent uv from managing Python system-wide, provide the `--no-shim` option during installation.
-->
Once Python is installed, it will be used by `uv` commands automatically.
!!! important
When Python is installed by uv, it will not be available globally (i.e. via the `python` command).
Support for this feature is planned for a future release. In the meantime, use
Support for this feature is in _preview_. See [Installing Python executables](../concepts/python-versions.md#installing-python-executables)
for details.
You can still use
[`uv run`](../guides/scripts.md#using-different-python-versions) or
[create and activate a virtual environment](../pip/environments.md) to use `python` directly.