Install and manage Python interpreter versions with uv...
Quick reference for installing and managing Python interpreter versions with UV.
| Use this skill when... | Use a focused sibling instead when... |
|---|---|
Installing a specific CPython or PyPy interpreter with uv python install |
Adding a Python library to a project — use uv-project-management |
Pinning a project to a Python version via .python-version or requires-python |
Installing a global Python CLI tool — use uv-tool-management |
| Switching between multiple installed interpreters for testing | Running a script with auto-managed Python — use uv-run |
# 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
# List all available versions
uv python list
# List only installed versions
uv python list --only-installed
# List with verbose details
uv python list --verbose
# 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
# 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
# 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
UV searches for Python in this order:
uv python installrequires-python field$PATH and standard locations# Pin creates this file
uv python pin 3.11
# File contents
3.11
# Exact version
uv python pin 3.11.5
[project]
requires-python = ">=3.11"
# UV respects this constraint
# Default implementation
uv python install 3.11
uv python install cpython@3.11
uv python install cpython@3.11.5
# Alternative Python implementation
uv python install pypy@3.9
uv python install pypy@3.10
# 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-*
# Initialize with specific Python
uv init --python 3.11 my-project
# Generates .python-version
cat .python-version
# 3.11
# 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
# 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
uv-project-management - Using pinned Python versions in projectsuv-workspaces - Python versions in monorepospython-testing - Testing across multiple Python versions
