uv Cheatsheet — Python Management

·Updated March 20th, 2026
pythonuvpython-versionspyenv

Install Python Versions

uv downloads pre-built CPython distributions from Astral’s python-build-standalone project. No compilation needed.

bash
# Install the latest Python
uv python install

# Install specific versions
uv python install 3.12
uv python install 3.12 3.13 3.14

# Install a precise patch version
uv python install 3.12.8

# Install a default `python` / `python3` executable (experimental)
uv python install --default

Installed Python executables land in ~/.local/bin/ (e.g., python3.12). If this isn’t in your $PATH:

bash
uv python update-shell

List Available & Installed Versions

bash
# Show installed versions
uv python list

# Show only uv-managed versions
uv python list --only-managed

Pin a Project to a Python Version

bash
# Creates / updates .python-version
uv python pin 3.12

# Pin to an exact version
uv python pin 3.12.8

The .python-version file is respected by uv run, uv sync, and uv venv. For projects requiring multiple versions (e.g., for tox-style testing), use a .python-versions file (one version per line).

Use a Specific Version Ad-Hoc

bash
# Create a venv with a specific version
uv venv --python 3.13

# Run a command with a specific version
uv run --python 3.11 -- python -c "import sys; print(sys.version)"

# Even use alternative implementations
uv run --python pypy@3.10 -- python --version

Upgrade Patch Versions (preview)

bash
# Upgrade to the latest patch release (e.g., 3.13.4 → 3.13.5)
uv python upgrade 3.13

Minor version upgrades (e.g., 3.12 → 3.13) are not transparent upgrades because they can affect dependency resolution.

Reinstall Managed Python

bash
uv python install --reinstall

Useful when a new build of the same version fixes bugs.

Automatic Downloads

By default, uv auto-downloads Python when it’s needed. For example, running uv venv on a machine with no Python will trigger an automatic install. To disable this:

bash
# Disable automatic downloads
export UV_PYTHON_DOWNLOADS=never

# Or per-command
uv run --no-managed-python main.py

Force System Python

bash
# Ignore uv-managed versions, use only system-installed Python
uv run --no-managed-python -- python --version

Key Directories

WhatDefault path (Linux)
Managed Python installs~/.local/share/uv/python/
Python executables~/.local/bin/

Override the install dir with UV_PYTHON_INSTALL_DIR.