Skip to main content
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: 
uv venv --python 3
uv venv --python 3.12
uv venv --python 3.12.3

​
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., [email protected]
  • <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:
Prefer managed Python over system Python, but prefer existing system Python over downloading.

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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us