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:

Managed Python

Python versions installed by uv itself

System Python

Python versions from the OS or other tools (pyenv, Homebrew, etc.)

uv treats all non-uv Python installations as “system” Python, including those managed by pyenv, Homebrew, or conda.

Requesting a Version

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

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:

Version Numbers

uv venv --python 3
uv venv --python 3.12
uv venv --python 3.12.3

Version Specifiers

uv venv --python '>=3.12,<3.13'
uv venv --python '>=3.8'

Implementations

uv venv --python cpython
uv venv --python pypy
uv venv --python cpython@3.12
uv venv --python cp312

Paths

uv venv --python /opt/homebrew/bin/python3
uv venv --python mypython3
uv venv --python /some/environment/

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:

uv python pin 3.12

Create a global .python-version:

uv python pin --global 3.12

Version File Format

Any version request format can be used, though version numbers are recommended for tool interoperability:

.python-version

3.12.3

Discovery of .python-version files can be disabled with --no-config.

Installing Python Versions

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

By default, Python versions are automatically downloaded as needed. You don’t need to use uv python install explicitly.

Installation Examples

# 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

Available Python versions are frozen per uv release. To install new Python versions, upgrade uv.

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:

uv python install 3.12 --default

Also installs:

• python - Default Python
• python3 - Python 3.x default

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

uv python update-shell

Version Precedence

uv prefers the latest patch version of each minor version:

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

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

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

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

If a virtual environment was created with an explicit patch version (uv venv -p 3.10.8), it won’t be automatically upgraded.

Minor Version Directories

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

~/.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:

pyproject.toml

[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

# 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:

# 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 Python in CPython 3.13+.

Python 3.13 Behavior

Free-threaded builds must be explicitly requested:

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:

uv venv --python 3.14+gil

Debug Python Variants

uv supports debug builds of Python with debug assertions enabled.

Debug builds are significantly slower and not appropriate for general use.

Explicitly request debug builds:

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:

pyproject.toml

[tool.uv]
# Only download during `uv python install`
python-downloads = "manual"

Or use the command-line flag:

uv sync --no-python-downloads

Python Version Preferences

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

managed (default)

Prefer managed Python over system Python, but prefer existing system Python over downloading.

only-managed

Only use managed Python installations.

uv sync --managed-python

system

Prefer system Python over managed Python.

only-system

Only use system Python installations.

uv sync --no-managed-python

Python Implementation Support

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

Implementation Names

CPython

cpython or cp

PyPy

pypy or pp

GraalPy

graalpy or gp

Pyodide

pyodide

Managed Python Distributions

CPython Distributions

uv uses pre-built distributions from Astral’s 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

These distributions have some behavior quirks due to portability. See the python-build-standalone quirks documentation.

PyPy Distributions

PyPy is no longer actively developed and only supports Python versions up to 3.11.

Provided by the PyPy project.

Pyodide Distributions

Provided by the Pyodide project. 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

A Python interpreter needs packages matching its architecture — all x86_64 or all aarch64.

Windows Registry Registration

On Windows, managed Python versions are registered in the Windows registry per PEP 514.

Use with the py launcher:

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

Projects

Learn about project structure and the requires-python field

Dependencies

Understand how Python versions affect dependency resolution

Cache

Learn where Python installations are cached