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

Support transparent Python patch version upgrades (#13954)

Browse source 
> NOTE: The PRs that were merged into this feature branch have all been
independently reviewed. But it's also useful to see all of the changes
in their final form. I've added comments to significant changes
throughout the PR to aid discussion.

This PR introduces transparent Python version upgrades to uv, allowing
for a smoother experience when upgrading to new patch versions.
Previously, upgrading Python patch versions required manual updates to
each virtual environment. Now, virtual environments can transparently
upgrade to newer patch versions.

Due to significant changes in how uv installs and executes managed
Python executables, this functionality is initially available behind a
`--preview` flag. Once an installation has been made upgradeable through
`--preview`, subsequent operations (like `uv venv -p 3.10` or patch
upgrades) will work without requiring the flag again. This is
accomplished by checking for the existence of a minor version symlink
directory (or junction on Windows).

### Features

* New `uv python upgrade` command to upgrade installed Python versions
to the latest available patch release:
``` 
# Upgrade specific minor version 
uv python upgrade 3.12 --preview
# Upgrade all installed minor versions
uv python upgrade --preview
```
* Transparent upgrades also occur when installing newer patch versions: 
```
uv python install 3.10.8 --preview
# Automatically upgrades existing 3.10 environments
uv python install 3.10.18
```
* Support for transparently upgradeable Python `bin` installations via
`--preview` flag
```
uv python install 3.13 --preview
# Automatically upgrades the `bin` installation if there is a newer patch version available
uv python upgrade 3.13 --preview
```
* Virtual environments can still be tied to a patch version if desired
(ignoring patch upgrades):
```
uv venv -p 3.10.8
```

### Implementation

Transparent upgrades are implemented using:
* Minor version symlink directories (Unix) or junctions (Windows)
* On Windows, trampolines simulate paths with junctions
* Symlink directory naming follows Python build standalone format: e.g.,
`cpython-3.10-macos-aarch64-none`
* Upgrades are scoped to the minor version key (as represented in the
naming format: implementation-minor version+variant-os-arch-libc)
* If the context does not provide a patch version request and the
interpreter is from a managed CPython installation, the `Interpreter`
used by `uv python run` will use the full symlink directory executable
path when available, enabling transparently upgradeable environments
created with the `venv` module (`uv run python -m venv`)

New types:
* `PythonMinorVersionLink`: in a sense, the core type for this PR, this
is a representation of a minor version symlink directory (or junction on
Windows) that points to the highest installed managed CPython patch
version for a minor version key.
* `PythonInstallationMinorVersionKey`: provides a view into a
`PythonInstallationKey` that excludes the patch and prerelease. This is
used for grouping installations by minor version key (e.g., to find the
highest available patch installation for that minor version key) and for
minor version directory naming.

### Compatibility

* Supports virtual environments created with:
  * `uv venv`
* `uv run python -m venv` (using managed Python that was installed or
upgraded with `--preview`)
  * Virtual environments created within these environments
* Existing virtual environments from before these changes continue to
work but aren't transparently upgradeable without being recreated
* Supports both standard Python (`python3.10`) and freethreaded Python
(`python3.10t`)
* Support for transparently upgrades is currently only available for
managed CPython installations

Closes #7287
Closes #7325
Closes #7892
Closes #9031
Closes #12977

---------

Co-authored-by: Zanie Blue <contact@zanie.dev>
This commit is contained in:
John Mumm 2025-06-20 10:17:13 -04:00 • committed by GitHub
parent 62365d4ec8
commit e9d5780369
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
73 changed files with 3022 additions and 306 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -123,7 +123,7 @@ present, uv will install all the Python versions listed in the file.
!!! important
Support for installing Python executables is in _preview_, this means the behavior is experimental
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:
@ -158,6 +158,70 @@ $ 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
```
## Upgrading Python versions
!!! important
Support for upgrading Python versions is in _preview_. This means the behavior is experimental
and subject to change.
Upgrades are only supported for uv-managed Python versions.
Upgrades are not currently supported for PyPy and GraalPy.
uv allows transparently upgrading Python versions to the latest patch release, e.g., 3.13.4 to
3.13.5. uv does not allow transparently upgrading across minor Python versions, e.g., 3.12 to 3.13,
because changing minor versions can affect dependency resolution.
uv-managed Python versions can be upgraded to the latest supported patch release with the
`python upgrade` command:
To upgrade a Python version to the latest supported patch release:
```console
$ uv python upgrade 3.12
```
To upgrade all installed Python versions:
```console
$ uv python upgrade
```
After an upgrade, uv will prefer the new version, but will retain the existing version as it may
still be used by virtual environments.
If the Python version was installed with preview enabled, e.g., `uv python install 3.12 --preview`,
virtual environments using the Python version will be automatically upgraded to the new patch
version.
!!! note
If the virtual environment was created _before_ opting in to the preview mode, it will not be
included in the automatic upgrades.
If a virtual environment was created with an explicitly requested patch version, e.g.,
`uv venv -p 3.10.8`, it will not be transparently upgraded to a new version.
### Minor version directories
Automatic upgrades for virtual environments are implemented using a directory with the Python minor
version, e.g.:
```
~/.local/share/uv/python/cpython-3.12-macos-aarch64-none
```
which is a symbolic link (on Unix) or junction (on Windows) pointing to a specific patch version:
```console
$ readlink ~/.local/share/uv/python/cpython-3.12-macos-aarch64-none
~/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none
```
If this link is resolved by another tool, e.g., by canonicalizing the Python interpreter path, and
used to create a virtual environment, it will not be automatically upgraded.
## Project Python versions
uv will respect Python requirements defined in `requires-python` in the `pyproject.toml` file during