uv.lock, Universal Resolution, Tool Isolation

Three uv concepts make it more than 'fast pip' — they're the reason it can replace half a dozen tools.

uv.lock — a real lockfile. uv.lock pins every direct and transitive dep with content hashes. Reproducibility is bit-exact across machines. uv sync installs precisely what's locked; if anything diverges, sync fails loudly. This is what requirements.txt always pretended to be and never was.

Universal resolution. uv.lock contains entries for multiple Python versions and platforms (macOS arm64, macOS x64, Linux, Windows). One lockfile, every target. That's how a team running macOS dev machines + a Linux CI server + a Windows Docker host all get reproducible installs from the same lockfile.

Tool isolation. uv tool install ruff installs ruff in its own private venv at ~/.local/share/uv/tools/ruff/, then exposes ruff on PATH. The tool can't conflict with your project's deps; your project can't break the tool. This is what pipx did, but built in.

Built-in Python management. uv python install 3.13 downloads a portable Python (from the python-build-standalone project) and registers it. Multiple versions coexist. uv python pin 3.13 writes .python-version to lock this project to that interpreter. No pyenv, no system-Python confusion.

Code

Anatomy of uv.lock·toml

# uv.lock (excerpt — auto-generated, NEVER hand-edit)
version = 1
requires-python = ">=3.11"
resolution-markers = ["sys_platform == 'darwin' and python_version >= '3.11'", ...]

[[package]]
name = "flask"
version = "3.0.3"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "https://...", hash = "sha256:abc..." }
wheels = [
  { url = "https://...", hash = "sha256:def..." },
]
dependencies = [
  { name = "blinker", marker = "..." },
  { name = "click", marker = "..." },
  { name = "itsdangerous", marker = "..." },
  { name = "jinja2", marker = "..." },
  { name = "werkzeug", marker = "..." },
]

Inspect managed Pythons·bash

# What Pythons does uv know about?
uv python list
# cpython-3.13.0-macos-aarch64-none    /Users/you/.local/share/uv/python/...
# cpython-3.12.4-macos-aarch64-none    /Users/you/.local/share/uv/python/...
# cpython-3.11.9-macos-aarch64-none    /Users/you/.local/share/uv/python/...
# (...and many available-but-not-installed entries)

# Install + use
uv python install 3.13
uv python pin 3.13            # writes .python-version

# This project now uses 3.13, regardless of system Python.

uv.lock, Universal Resolution, Tool Isolation

Code

External links

Exercise

Progress

Comments 0