Python notes

python_vesions

Python Versions in UV

Python Installations

  • Managed: Installed by UV (uv python install).
  • System: Discovered on your machine, including OS-installed and pyenv versions.

Requesting a Python Version

Use --python flag or .python-version file. Supported formats:

  • Version: 3, 3.12, 3.12.3
  • Specifier: >=3.11,<3.13
  • Implementation: cpython, pypy, cp312, pypy@3.10
  • Full triplet: cpython-3.12.3-macos-aarch64-none
  • Path: /usr/bin/python3, mypython3, /env/

.python-version File

  • Defines default Python version per project or globally.
  • Created with: 
    uv python pin         # local
uv python pin --global  # global
  • Disable discovery with --no-config.

Installing Python Versions 

uv python install 3.12
uv python install 3.11 3.12 3.13
uv python install ">=3.9,<3.11"
  • Uses frozen list of available versions.
  • Use --preview to install executables into ~/.local/bin.
  • Add --default to install as python / python3.

Installing Executables 

uv python install 3.12 --preview
uv python install 3.12 --default --preview
  • Adds python3.12, or python and python3 (with --default) to ~/.local/bin.
  • Use uv tool update-shell to add to PATH.

Project Integration

  • UV respects requires-python in pyproject.toml.
  • Uses first compatible Python unless overridden.

Listing Python Versions 

uv python list
uv python list 3.13
uv python list pypy
uv python list --all-versions
uv python list --only-installed

Finding Python Executables 

uv python find
uv python find ">=3.11"
uv python find --system
  • Returns the path to the first compatible Python interpreter.

Discovery Order

  1. Managed UV installations
  2. Executables on PATH: python, python3, etc.
  3. Windows registry (Windows only)
  4. Virtual environments (unless --system is used)

Pre-releases

  • Only used if no stable version is available.
  • Will not replace a stable version if both are valid.

Disabling Auto Downloads 

--no-python-downloads
  • Or set python-downloads = "manual" in config.

Controlling Preferences 

--managed-python        # Only managed versions
--no-managed-python     # Only system versions

Config setting: python-preference = "only-managed" | "system" | "only-system"

Supported Implementations

  • CPython: cpython, cp
  • PyPy: pypy, pp
  • GraalPy: graalpy, gp

Python Distributions

  • CPython: Pre-built via python-build-standalone.
  • PyPy: Official PyPy binaries.

Multi-version Projects

  • Use .python-versions to list all required versions.
  • UV will install all versions listed.

These tools enable precise, reproducible Python version management within and across UV-managed projects.

Previous projects Next resolutions