Python management

uv python manages the Python interpreters on the user's machine: discovering existing ones, downloading new ones, pinning a version per-project, and serving them up to other commands.

Sources of interpreters

crates/uv-python/src/discovery.rs (the largest single file in uv at 175 KB) is the authoritative list of where uv looks:

1. Active virtualenv (VIRTUAL_ENV).
2. Discovered virtualenvs (.venv, venv near the project root).
3. UV_PYTHON_INSTALL_DIR — the managed Python directory.
4. PATH.
5. Windows registry (HKEY_LOCAL_MACHINE\SOFTWARE\Python\PythonCore\...).
6. Conda / pyenv shims (best-effort).

Each discovered interpreter is interrogated: uv runs a small script (crates/uv-python/python/) to read out sys.version, sys.platform, sysconfig.get_paths(), and the platform tag set.

Managed Pythons

uv python install 3.13 downloads a python-build-standalone tarball, verifies it, and extracts into ~/.local/share/uv/python/cpython-3.13.X-....

The "what's available?" list ships in crates/uv-python/src/'s embedded download index. CI re-generates it via cargo dev-style scripts when a new python-build-standalone release ships.

Pinning

uv python pin 3.12 writes .python-version next to pyproject.toml. Subsequent commands honor the pin (when the user hasn't passed --python explicitly). The file is a single version-spec line, intentionally compatible with pyenv's format.

Update shell

uv python update-shell ensures the configured Python's bin directory is on PATH. Like uv tool update-shell, this is delegated to uv-shell for the shell-specific logic.

See also

• crates/uv-python — the deep dive.
• crates/uv-shell — PATH manipulation.
• crates/uv-state — managed-Python directory.