mirror of
https://github.com/astral-sh/uv.git
synced 2025-07-07 21:35:00 +00:00
e9d5780369
> 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>
150 lines
4.8 KiB
Markdown
150 lines
4.8 KiB
Markdown
---
|
|
title: Installing and managing Python
|
|
description:
|
|
A guide to using uv to install Python, including requesting specific versions, automatic
|
|
installation, viewing installed versions, and more.
|
|
---
|
|
|
|
# Installing Python
|
|
|
|
If Python is already installed on your system, uv will
|
|
[detect and use](#using-existing-python-versions) it without configuration. However, uv can also
|
|
install and manage Python versions. uv [automatically installs](#automatic-python-downloads) missing
|
|
Python versions as needed — you don't need to install Python to get started.
|
|
|
|
## Getting started
|
|
|
|
To install the latest Python version:
|
|
|
|
```console
|
|
$ uv python install
|
|
```
|
|
|
|
!!! note
|
|
|
|
Python does not publish official distributable binaries. As such, uv uses distributions from the 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.
|
|
|
|
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 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.
|
|
|
|
## Installing a specific version
|
|
|
|
To install a specific Python version:
|
|
|
|
```console
|
|
$ uv python install 3.12
|
|
```
|
|
|
|
To install multiple Python versions:
|
|
|
|
```console
|
|
$ uv python install 3.11 3.12
|
|
```
|
|
|
|
To install an alternative Python implementation, e.g., PyPy:
|
|
|
|
```console
|
|
$ uv python install pypy@3.10
|
|
```
|
|
|
|
See the [`python install`](../concepts/python-versions.md#installing-a-python-version) documentation
|
|
for more details.
|
|
|
|
## Reinstalling Python
|
|
|
|
To reinstall uv-managed Python versions, use `--reinstall`, e.g.:
|
|
|
|
```console
|
|
$ uv python install --reinstall
|
|
```
|
|
|
|
This will reinstall all previously installed Python versions. Improvements are constantly being
|
|
added to the Python distributions, so reinstalling may resolve bugs even if the Python version does
|
|
not change.
|
|
|
|
## Viewing Python installations
|
|
|
|
To view available and installed Python versions:
|
|
|
|
```console
|
|
$ uv python list
|
|
```
|
|
|
|
See the [`python list`](../concepts/python-versions.md#viewing-available-python-versions)
|
|
documentation for more details.
|
|
|
|
## Automatic Python downloads
|
|
|
|
Python does not need to be explicitly installed to use uv. By default, uv will automatically
|
|
download Python versions when they are required. For example, the following would download Python
|
|
3.12 if it was not installed:
|
|
|
|
```console
|
|
$ uvx python@3.12 -c "print('hello world')"
|
|
```
|
|
|
|
Even if a specific Python version is not requested, uv will download the latest version on demand.
|
|
For example, if there are no Python versions on your system, the following will install Python
|
|
before creating a new virtual environment:
|
|
|
|
```console
|
|
$ uv venv
|
|
```
|
|
|
|
!!! tip
|
|
|
|
Automatic Python downloads can be [easily disabled](../concepts/python-versions.md#disabling-automatic-python-downloads) if you want more control over when Python is downloaded.
|
|
|
|
<!-- 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.
|
|
-->
|
|
|
|
## Using existing Python versions
|
|
|
|
uv will use existing Python installations if present on your system. There is no configuration
|
|
necessary for this behavior: uv will use the system Python if it satisfies the requirements of the
|
|
command invocation. See the
|
|
[Python discovery](../concepts/python-versions.md#discovery-of-python-versions) documentation for
|
|
details.
|
|
|
|
To force uv to use the system Python, provide the `--no-managed-python` flag. See the
|
|
[Python version preference](../concepts/python-versions.md#requiring-or-disabling-managed-python-versions)
|
|
documentation for more details.
|
|
|
|
## Upgrading Python versions
|
|
|
|
!!! important
|
|
|
|
Support for upgrading Python patch versions is in _preview_. This means the behavior is
|
|
experimental and subject to change.
|
|
|
|
To upgrade a Python version to the latest supported patch release:
|
|
|
|
```console
|
|
$ uv python upgrade 3.12
|
|
```
|
|
|
|
To upgrade all uv-managed Python versions:
|
|
|
|
```console
|
|
$ uv python upgrade
|
|
```
|
|
|
|
See the [`python upgrade`](../concepts/python-versions.md#upgrading-python-versions) documentation
|
|
for more details.
|
|
|
|
## Next steps
|
|
|
|
To learn more about `uv python`, see the [Python version concept](../concepts/python-versions.md)
|
|
page and the [command reference](../reference/cli.md#uv-python).
|
|
|
|
Or, read on to learn how to [run scripts](./scripts.md) and invoke Python with uv.
|