Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Touch-ups to the Python install guide #11116

Merged
merged 1 commit into from
Jan 30, 2025
Merged

Touch-ups to the Python install guide #11116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/concepts/python-versions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,8 @@ To exclude downloads and only show installed Python versions:
$ uv python list --only-installed
```

See the [`uv python list`](../reference/cli.md#uv-python-list) reference for more details.

## Finding a Python executable

To find a Python executable, use the `uv python find` command:
Expand Down
40 changes: 21 additions & 19 deletions docs/guides/install-python.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,8 @@ description:

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 for you.

!!! tip

uv will [automatically fetch Python versions](#automatic-python-downloads) as needed — you don't need to install Python to get started.

<!-- TODO(zanieb): I don't love this heading. -->
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

Expand All @@ -25,12 +20,9 @@ To install the latest Python version:
$ uv python install
```

This will install a uv-managed Python version even if there is already a Python installation on your
system. If you've previously installed Python with uv, a new version will not be installed.

!!! note

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.
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.

Expand Down Expand Up @@ -67,6 +59,18 @@ $ uv python install [email protected]
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:
Expand All @@ -78,21 +82,19 @@ $ uv python list
See the [`python list`](../concepts/python-versions.md#viewing-available-python-versions)
documentation for more details.

<!--TODO(zanieb): The above should probably link to a CLI reference and that content should be moved out of that file -->

## Automatic Python downloads

Note that 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:
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
$ uv run --python 3.12 python -c "print('hello world')"
$ 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, the following will create a new virtual environment and download a managed Python
version if Python is not found:
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
Expand Down
Loading