> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Versions

> Learn how uv discovers, installs, and manages Python versions across your projects

A Python version is composed of a Python interpreter (the `python` executable), the standard library, and other supporting files.

## Managed vs System Python

uv supports two types of Python installations:

<CardGroup cols={2}>
  <Card title="Managed Python" icon="download">
    Python versions installed by uv itself
  </Card>

  <Card title="System Python" icon="computer">
    Python versions from the OS or other tools (pyenv, Homebrew, etc.)
  </Card>
</CardGroup>

<Note>
  uv treats all non-uv Python installations as "system" Python, including those managed by pyenv, Homebrew, or conda.
</Note>

## Requesting a Version

Specify a Python version with the `--python` flag in most uv commands:

```bash  theme={null}
uv venv --python 3.11.6
```

uv will ensure Python 3.11.6 is available — downloading and installing it if necessary — then create the virtual environment with it.

### Version Request Formats

The following request formats are supported:

<Tabs>
  <Tab title="Version Numbers">
    ```bash  theme={null}
    uv venv --python 3
    uv venv --python 3.12
    uv venv --python 3.12.3
    ```
  </Tab>

  <Tab title="Version Specifiers">
    ```bash  theme={null}
    uv venv --python '>=3.12,<3.13'
    uv venv --python '>=3.8'
    ```
  </Tab>

  <Tab title="Implementations">
    ```bash  theme={null}
    uv venv --python cpython
    uv venv --python pypy
    uv venv --python cpython@3.12
    uv venv --python cp312
    ```
  </Tab>

  <Tab title="Paths">
    ```bash  theme={null}
    uv venv --python /opt/homebrew/bin/python3
    uv venv --python mypython3
    uv venv --python /some/environment/
    ```
  </Tab>
</Tabs>

### Complete Format Reference

* `<version>` - e.g., `3`, `3.12`, `3.12.3`
* `<version-specifier>` - e.g., `>=3.12,<3.13`
* `<version><short-variant>` - e.g., `3.13t`, `3.12.0d`
* `<version>+<variant>` - e.g., `3.13+freethreaded`, `3.12.0+debug`
* `<implementation>` - e.g., `cpython`, `pypy`
* `<implementation>@<version>` - e.g., `cpython@3.12`
* `<implementation><version>` - e.g., `cpython3.12`, `cp312`
* `<implementation>-<version>-<os>-<arch>-<libc>` - e.g., `cpython-3.12.3-macos-aarch64-none`
* `<executable-path>` - e.g., `/opt/homebrew/bin/python3`
* `<executable-name>` - e.g., `mypython3`
* `<install-dir>` - e.g., `/some/environment/`

## Python Version Files

The `.python-version` file sets a default Python version request.

### How It Works

uv searches for `.python-version` in:

1. The current working directory
2. Each parent directory
3. The user-level configuration directory (if none found)

### Creating Version Files

Create a project-local `.python-version`:

```bash  theme={null}
uv python pin 3.12
```

Create a global `.python-version`:

```bash  theme={null}
uv python pin --global 3.12
```

### Version File Format

Any [version request format](#version-request-formats) can be used, though version numbers are recommended for tool interoperability:

```text .python-version theme={null}
3.12.3
```

<Info>
  Discovery of `.python-version` files can be disabled with `--no-config`.
</Info>

## Installing Python Versions

uv bundles downloadable CPython and PyPy distributions for macOS, Linux, and Windows.

<Note>
  By default, Python versions are automatically downloaded as needed. You don't need to use `uv python install` explicitly.
</Note>

### Installation Examples

```bash  theme={null}
# Install specific version
uv python install 3.12.3

# Install latest patch version
uv python install 3.12

# Install version matching constraints
uv python install '>=3.8,<3.10'

# Install multiple versions
uv python install 3.9 3.10 3.11

# Install PyPy
uv python install pypy
```

### Default Install Behavior

Without arguments, `uv python install` will:

* Verify a managed Python is installed, OR
* Install the latest Python version, OR
* Install versions from `.python-version` or `.python-versions`

<Warning>
  Available Python versions are frozen per uv release. To install new Python versions, upgrade uv.
</Warning>

## Installing Python Executables

uv installs Python executables into your `PATH` by default.

### Executable Installation

On Unix, `uv python install 3.12` installs to `~/.local/bin`, creating:

* `python3.12` - Version-specific executable

With the `--default` flag:

```bash  theme={null}
uv python install 3.12 --default
```

Also installs:

* `python` - Default Python
* `python3` - Python 3.x default

<Tip>
  If `~/.local/bin` is not in your PATH, add it with:

  ```bash  theme={null}
  uv python update-shell
  ```
</Tip>

### Version Precedence

uv prefers the latest patch version of each minor version:

```bash  theme={null}
uv python install 3.12.7  # Adds python3.12 → 3.12.7
uv python install 3.12.6  # Does not update python3.12
uv python install 3.12.8  # Updates python3.12 → 3.12.8
```

## Upgrading Python Versions

<Warning>
  Upgrades are only supported for uv-managed Python versions. PyPy, GraalPy, and Pyodide upgrades are not currently supported.
</Warning>

uv allows transparent upgrades to the latest patch release (e.g., 3.13.4 → 3.13.5). Minor version upgrades (e.g., 3.12 → 3.13) are not automatic as they can affect dependency resolution.

### Upgrade Commands

```bash  theme={null}
# Upgrade specific Python version
uv python upgrade 3.12

# Upgrade all installed versions
uv python upgrade
```

### Virtual Environment Auto-Upgrade

After upgrading, virtual environments using the Python version are automatically upgraded to the new patch version.

<Note>
  If a virtual environment was created with an explicit patch version (`uv venv -p 3.10.8`), it won't be automatically upgraded.
</Note>

### Minor Version Directories

Automatic upgrades use symbolic links (Unix) or junctions (Windows):

```bash  theme={null}
~/.local/share/uv/python/cpython-3.12-macos-aarch64-none
# ↓ links to
~/.local/share/uv/python/cpython-3.12.11-macos-aarch64-none
```

## Project Python Versions

For projects with `pyproject.toml`, uv respects the `requires-python` field:

```toml pyproject.toml theme={null}
[project]
name = "example"
version = "0.1.0"
requires-python = ">=3.11"
```

The first compatible Python version will be used, unless overridden by:

* `.python-version` file
* `--python` flag

## Viewing Available Versions

### List Installed and Available

```bash  theme={null}
# Default view
uv python list

# Show all patch versions and platforms
uv python list --all-versions --all-platforms

# Filter to specific versions
uv python list 3.13
uv python list pypy

# Show only installed versions
uv python list --only-installed
```

## Finding Python Executables

Find the path to a Python executable:

```bash  theme={null}
# Find any Python
uv python find

# Find Python 3.11+
uv python find '>=3.11'

# Ignore virtual environments
uv python find --system
```

## Discovery of Python Versions

When searching for a Python version, uv checks:

1. **Managed Python** - In `UV_PYTHON_INSTALL_DIR`
2. **PATH executables** - `python`, `python3`, `python3.x` (Unix) or `python.exe` (Windows)
3. **Windows registry** - Microsoft Store and registered interpreters

### Discovery Behavior

* **Managed Python** - Prefers newer versions first
* **System Python** - Uses first compatible version found
* **Virtual environments** - Checked before system Python in some contexts

## Python Pre-releases

Pre-release Python versions (alpha, beta, RC) are not selected by default:

* Used only if no stable release matches the request
* Used if explicitly requested via path
* Used if only pre-release available for request

## Free-threaded Python

uv supports [free-threaded](https://docs.python.org/3.14/glossary.html#term-free-threading) Python in CPython 3.13+.

### Python 3.13 Behavior

Free-threaded builds must be explicitly requested:

```bash  theme={null}
uv venv --python 3.13t
uv venv --python 3.13+freethreaded
```

### Python 3.14+ Behavior

Free-threaded interpreters can be used without explicit selection, but GIL-enabled builds are preferred.

To require GIL-enabled Python:

```bash  theme={null}
uv venv --python 3.14+gil
```

## Debug Python Variants

uv supports [debug builds](https://docs.python.org/3.14/using/configure.html#debug-build) of Python with debug assertions enabled.

<Warning>
  Debug builds are significantly slower and not appropriate for general use.
</Warning>

Explicitly request debug builds:

```bash  theme={null}
uv venv --python 3.13d
uv venv --python 3.13+debug
```

## Disabling Automatic Downloads

By default, uv automatically downloads Python when needed. Control this with the `python-downloads` setting:

```toml pyproject.toml theme={null}
[tool.uv]
# Only download during `uv python install`
python-downloads = "manual"
```

Or use the command-line flag:

```bash  theme={null}
uv sync --no-python-downloads
```

## Python Version Preferences

The `python-preference` setting controls which Python installations to prefer:

<Tabs>
  <Tab title="managed (default)">
    Prefer managed Python over system Python, but prefer existing system Python over downloading.
  </Tab>

  <Tab title="only-managed">
    Only use managed Python installations.

    ```bash  theme={null}
    uv sync --managed-python
    ```
  </Tab>

  <Tab title="system">
    Prefer system Python over managed Python.
  </Tab>

  <Tab title="only-system">
    Only use system Python installations.

    ```bash  theme={null}
    uv sync --no-managed-python
    ```
  </Tab>
</Tabs>

## Python Implementation Support

uv supports CPython, PyPy, Pyodide, and GraalPy implementations.

### Implementation Names

<CardGroup cols={2}>
  <Card title="CPython">
    `cpython` or `cp`
  </Card>

  <Card title="PyPy">
    `pypy` or `pp`
  </Card>

  <Card title="GraalPy">
    `graalpy` or `gp`
  </Card>

  <Card title="Pyodide">
    `pyodide`
  </Card>
</CardGroup>

## Managed Python Distributions

### CPython Distributions

uv uses pre-built distributions from Astral's [`python-build-standalone`](https://github.com/astral-sh/python-build-standalone) project, which:

* Are self-contained and highly portable
* Include performance optimizations (PGO, LTO)
* Are used by Mise, rules\_python, and other tools

<Note>
  These distributions have some behavior quirks due to portability. See the [python-build-standalone quirks](https://gregoryszorc.com/docs/python-build-standalone/main/quirks.html) documentation.
</Note>

### PyPy Distributions

<Warning>
  PyPy is no longer actively developed and only supports Python versions up to 3.11.
</Warning>

Provided by the [PyPy project](https://pypy.org).

### Pyodide Distributions

Provided by the [Pyodide project](https://github.com/pyodide/pyodide). Pyodide is CPython ported to WebAssembly/Emscripten.

## Platform Support

### x86\_64 Emulation on aarch64

Both macOS (Rosetta 2) and Windows (WoA emulation) support running x86\_64 binaries on aarch64 through transparent emulation.

You can:

* Use x86\_64 uv on aarch64
* Use x86\_64 Python on aarch64
* Mix architectures for uv and Python

<Warning>
  A Python interpreter needs packages matching its architecture — all x86\_64 or all aarch64.
</Warning>

## Windows Registry Registration

On Windows, managed Python versions are registered in the Windows registry per [PEP 514](https://peps.python.org/pep-0514/).

Use with the `py` launcher:

```bash  theme={null}
uv python install 3.13.1
py -V:Astral/CPython3.13.1
```

On uninstall, uv removes the registry entry and any broken entries.

## Related Documentation

<CardGroup cols={2}>
  <Card title="Projects" icon="folder" href="/concepts/projects">
    Learn about project structure and the requires-python field
  </Card>

  <Card title="Dependencies" icon="box" href="/concepts/dependencies">
    Understand how Python versions affect dependency resolution
  </Card>

  <Card title="Cache" icon="database" href="/concepts/cache">
    Learn where Python installations are cached
  </Card>
</CardGroup>


Built with [Mintlify](https://mintlify.com).