Skip to content

uv

This is a tool reference

What a tool or project is, who makes it, and what it is for, whether someone else wrote it or I did. Everything I have learned about it lives elsewhere and links back here.

uv1 is a Python package and project manager that replaces the pip / pip-tools / pipx / venv stack with one binary. It is the tool this knowledge base and its publishing stack install through, and the reason a Python environment here is reproducible rather than merely described.
Author Astral
Licence Apache-2.0 (dual-licensed with MIT)
Language Rust
Distribution A standalone installer, pipx install uv, Homebrew, and most distro repositories
Source github.com/astral-sh/uv
Version read 0.12.13

What it is

Two files carry the state, and the distinction between them is the whole point. pyproject.toml is the manifest: what you declare, usually loosely, as mkdocs-material with no version or mkdocs>=1.6,<2. uv.lock is the lockfile: the exact resolution of that manifest, every package with a pinned version and hashes, across every platform the project supports.

The lockfile is always the larger of the two, because it also pins everything your dependencies depend on. A manifest naming ten packages routinely locks fifty, and the forty that appear in only one of the files are the ones nobody chose deliberately. That asymmetry is what Keep transitive dependencies in the regular update cycle is about.

The commands that matter for that split:
uv lock Resolve the manifest into the lockfile
uv lock --upgrade Re-resolve everything to the newest versions the manifest permits, transitive packages included
uv lock --upgrade-package <name> Re-resolve one package and whatever that forces, leaving the rest pinned
uv sync Make the environment match the lockfile exactly
uv sync --frozen The same, but fail rather than update a stale lockfile - the CI form, per Install from a frozen lockfile in CI
uv run Run a command in that environment, syncing first

uv run also executes a single file's PEP 723 inline metadata without a project at all, which is how the standalone scripts here declare their own dependencies.

Why it matters here

It is the substrate under the publishing stack, and the reason several principles in this bundle can be stated concretely rather than as good intentions: a frozen lockfile in CI, a guarded Python version, and dev tooling resolved through an ephemeral runner instead of an activated virtualenv.

It is also one half of an automation problem. An update bot has to understand both files to do its job, and Dependabot's uv support declines transitive security updates it has resolved records what happens when it is pointed at the manifest and left there.

The following pages link to this page:

  1. uv: documentation, last modified 2026-09-11 ↩