UV Python Version Management

Quick reference for installing and managing Python interpreter versions with UV.

When This Skill Applies

• Installing specific Python versions

• Switching between multiple Python versions

• Pinning Python versions for projects

• Managing CPython and PyPy interpreters

• Finding and listing installed Python versions

Quick Reference

Installing Python Versions

Install latest Python

uv python install

Install specific version

uv python install 3.11 uv python install 3.12 uv python install 3.10 3.11 3.12

Install exact version

uv python install 3.11.5 uv python install cpython@3.11.5

Install PyPy

uv python install pypy@3.9 uv python install pypy@3.10

Listing Python Versions

List all available versions

uv python list

List only installed versions

uv python list --only-installed

List with verbose details

uv python list --verbose

Pinning Python Versions

Pin version for current project

uv python pin 3.11 uv python pin 3.12.1

Pin PyPy

uv python pin pypy@3.9

Pin with version file

Creates/updates .python-version

Finding Python Interpreters

Find any Python installation

uv python find

Find specific version

uv python find 3.11 uv python find 3.12

Find PyPy

uv python find pypy uv python find pypy@3.9

Using Specific Python Versions

In project commands

uv run --python 3.11 script.py uv run --python 3.12 pytest

Creating virtual environments

uv venv --python 3.11 uv venv --python 3.10 .venv-py310

Initializing projects

uv init --python 3.12 my-project

Python Version Sources

UV searches for Python in this order:

• UV-managed - Installed via uv python install

• .python-version - Pin file in project directory

• pyproject.toml - requires-python field

• System Python - Existing system installations

• Environment - $PATH and standard locations

Version Pinning

.python-version File

Pin creates this file

uv python pin 3.11

File contents

3.11

Exact version

uv python pin 3.11.5

pyproject.toml

[project] requires-python = ">=3.11"

UV respects this constraint

Supported Python Implementations

CPython

Default implementation

uv python install 3.11 uv python install cpython@3.11 uv python install cpython@3.11.5

PyPy

Alternative Python implementation

uv python install pypy@3.9 uv python install pypy@3.10

Common Commands

Install and pin latest Python 3.12

uv python install 3.12 && uv python pin 3.12

Install multiple versions for testing

uv python install 3.10 3.11 3.12

Check which Python is active

uv python find uv run python --version

Uninstall version (manual)

rm -rf ~/.local/share/uv/python/cpython-3.11.5-*

Integration with Projects

Project Initialization

Initialize with specific Python

uv init --python 3.11 my-project

Generates .python-version

cat .python-version

3.11

Running Commands

Use project's pinned Python

uv run python script.py

Override with specific version

uv run --python 3.12 script.py

Use system Python

uv run --python python3 script.py

Multi-Version Testing

Test across Python versions

uv run --python 3.10 pytest uv run --python 3.11 pytest uv run --python 3.12 pytest

Create version-specific venvs

uv venv --python 3.10 .venv-py310 uv venv --python 3.11 .venv-py311 uv venv --python 3.12 .venv-py312

Key Features

• Fast downloads: Parallel downloads with caching

• Automatic: Downloads versions on-demand

• Isolated: UV-managed versions don't conflict with system Python

• Portable: Uses standalone Python distributions

• Cross-platform: Works on Linux, macOS, and Windows

See Also

• uv-project-management

• Using pinned Python versions in projects

• uv-workspaces

• Python versions in monorepos

• python-testing

• Testing across multiple Python versions

References

• Official docs: https://docs.astral.sh/uv/guides/install-python/

• Python standalone builds: https://github.com/indygreg/python-build-standalone

• Detailed guide: See REFERENCE.md in this skill directory