This page documents uv's managed Python installation system, which allows uv to automatically download, install, and manage Python interpreters. For information about discovering existing Python installations, see Python Discovery. For information about creating virtual environments, see Virtual Environment Management.
The managed Python system provides isolated, versioned Python installations that uv downloads and maintains in a dedicated directory. Unlike system Python installations, managed Pythons are:
sysconfig adjustments [crates/uv-python/src/sysconfig/mod.rs:1-20].The system primarily utilizes builds from python-build-standalone supporting CPython, PyPy, and other implementations across multiple platforms [crates/uv-python/src/downloads.rs:163-182].
Managed installations are stored in a hierarchical structure, typically under ~/.local/uv/python or a path specified by UV_PYTHON_INSTALL_DIR [crates/uv-python/src/managed.rs:129-141].
Title: Managed Python Directory Hierarchy
Sources:
| Component | Location | Purpose |
|---|---|---|
| Root directory | ~/.local/uv/python (default) | Top-level managed installations directory [crates/uv-python/src/managed.rs:129-141] |
.lock | {root}/.lock | Process lock preventing concurrent modifications [crates/uv-python/src/managed.rs:114-121] |
.temp/ | {root}/.temp | Scratch directory for downloads in progress [crates/uv-python/src/managed.rs:151-153] |
| Installation directories | {root}/{key}/ | Individual Python installations keyed by PythonInstallationKey [crates/uv-python/src/managed.rs:260-264] |
| Minor version links | {root}/{implementation}-{major}.{minor}-{platform}/ | Symlinks to latest patch (preview mode only) [crates/uv-python/src/managed.rs:839-842] |
The installation pipeline transforms a high-level PythonRequest into a functional local interpreter.
Title: Python Installation Data Flow
Sources:
The InstallRequest struct combines user requests with download metadata from download-metadata.json [crates/uv-python/download-metadata.json:1-18]:
Sources:
Downloads are fetched with retry logic and progress reporting via PythonDownloadReporter [crates/uv/src/commands/python/install.rs:41-43]:
python-build-standalone releases on GitHub [crates/uv-python/download-metadata.json:14]ExponentialBackoff for network errors [crates/uv-python/src/downloads.rs:15]Sources:
After extraction, installations undergo several patching operations in ManagedPythonInstallation::install [crates/uv-python/src/managed.rs:351-392]:
Creates lib/python{version}/EXTERNALLY-MANAGED per PEP 668 to prevent pip from modifying the uv-managed installation [crates/uv-python/src/managed.rs:394-431].
Patches _sysconfigdata_*.py files to make paths relative instead of absolute, enabling the installation to be relocated [crates/uv-python/src/managed.rs:433-440]. This utilizes DEFAULT_VARIABLE_UPDATES to replace hardcoded build paths with generic placeholders like cc or c++ [crates/uv-python/src/sysconfig/generated_mappings.rs:15-16].
Sources:
Ensures standard executable names exist in the installation directory (e.g., python, python3, python3.x) by creating symlinks or copies [crates/uv-python/src/managed.rs:512-546].
Writes .uv-build file recording the build version, enabling tracking of specialized builds (e.g., debug, freethreaded) [crates/uv-python/src/managed.rs:548-575].
On macOS, patches libpython*.dylib to use @loader_path instead of absolute paths using macos_dylib::patch_dylib, making the installation relocatable [crates/uv-python/src/managed.rs:577-632].
uv can link managed Pythons into a global bin directory to make them available in the user's PATH.
Title: Executable Linking Logic
Sources:
The bin directory is determined by python_executable_dir() [crates/uv-python/src/managed.rs:639-689]:
UV_PYTHON_BIN_DIR environment variable.~/.local/bin on Unix).On Windows, links are implemented using a launcher trampoline to avoid symlink permission issues [crates/uv-python/src/managed.rs:748-772]. On Unix, standard symlinks are used via replace_symlink [crates/uv-python/src/managed.rs:788-812].
In preview mode, uv creates intermediate symlink directories for minor versions (e.g., cpython-3.12-... pointing to cpython-3.12.7-...) [crates/uv-python/src/managed.rs:839-842].
When upgrading patch versions, the minor version link is updated to point to the new target [crates/uv-python/src/managed.rs:945-965]. This allows existing bin links or virtual environments pointing to the minor version path to receive the update automatically [crates/uv/src/commands/python/install.rs:525-541].
Sources:
On Windows, managed installations can optionally register themselves in the Windows Registry per PEP 514 [crates/uv-python/src/windows_registry.rs:1-10].
| Function | Purpose |
|---|---|
create_registry_entry() | Register new installation [crates/uv-python/src/managed.rs:1086-1110] |
remove_registry_entry() | Unregister on uninstall [crates/uv/src/commands/python/uninstall.rs:144-154] |
Registry integration is controlled by the --registry flag on uv python install [crates/uv/src/commands/python/install.rs:188].
The Changelog struct tracks installation state changes during an operation [crates/uv/src/commands/python/install.rs:111-117]:
Change events categorize operations into Added, Removed, or Reinstalled [crates/uv/src/commands/python/install.rs:121-141].
Sources:
Process-level locking via ManagedPythonInstallations::lock prevents corruption when multiple uv instances attempt to modify the installation directory [crates/uv-python/src/managed.rs:114-121].
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.