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

Simplify managed Python flags (#12246)

Browse source 
Currently, for users to specify at the command line whether to use
uv-managed or system Python interpreters, they use the
`--python-preference` parameter, which takes four possible values. This
is more complex than necessary since the normal case is to either say
"only managed" or "not managed". This PR hides the old
`--python-preference` parameter from help and documentation and adds two
new flags: `--managed-python` and `--no-managed-python` to capture the
"only managed" and "not managed" cases.

I have successfully tested this locally but currently cannot add
snapshot tests because of problems with distinguishing managed vs.
system interpreters in CI (and non-determinism when run on different
developers' machines). The `--python-preference` test in
`tool-install.rs` is currently ignored for this reason. See #5144 and
#7473.

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
This commit is contained in:
John Mumm 2025-03-18 18:13:14 +01:00 • committed by GitHub
parent e9d2b6ecea
commit f66ce58a09
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
8 changed files with 569 additions and 716 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -275,24 +275,43 @@ during `uv python install`.
[persistent configuration file](../configuration/files.md) to change the default behavior, or
the `--no-python-downloads` flag can be passed to any uv command.
## Adjusting Python version preferences
## Requiring or disabling managed Python versions
By default, uv will attempt to use Python versions found on the system and only download managed
interpreters when necessary.
Python versions when necessary. To ignore system Python versions, and only use managed Python
versions, use the `--managed-python` flag:
The [`python-preference`](../reference/settings.md#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
```console
$ uv python list --managed-python
```
Similarly, to ignore managed Python versions and only use system Python versions, use the
`--no-managed-python` flag:
```console
$ uv python list --no-managed-python
```
To change uv's default behavior in a configuration file, use the
[`python-preference` setting](#adjusting-python-version-preferences).
## Adjusting Python version preferences
The [`python-preference`](../reference/settings.md#python-preference) setting determines whether to
prefer using Python installations that are already present on the system, or those that are
downloaded and installed by uv.
By default, the `python-preference` 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
- `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.
- `only-managed`: Only use managed Python installations; never use system Python installations.
Equivalent to `--managed-python`.
- `system`: Prefer system Python installations over managed Python installations.
- `only-system`: Only use system Python installations; never use managed Python installations.
Equivalent to `--no-managed-python`.
!!! note