TD-014-uv-for-pin-lock-dependencies.md

id	TD-014
title	uv for pinning and locking dependencies
status	accepted
date	2026-06-09
supersedes
superseded_by
tags	tooling dependencies reproducibility

TD-014: uv for pinning and locking dependencies

Context

The project's guiding principle is reproducibility (TD-001). We need a dependency/venv manager for the host CLI that produces a deterministic lock and is fast.

Decision

We use uv: uv sync creates the .venv and generates/uses uv.lock, which is committed to git. The CLI is launched with uv run carbon ....

Rationale

uv is very fast, produces a deterministic lock, and handles venv + install in a single tool. Committing uv.lock makes the host environment reproducible bit-for-bit, in line with the tool's "everything reproducible" philosophy. The .venv/ stays git-ignored, the lock does not.

Consequences

• Positive: fast, deterministic install; a reproducible host environment; a single tool for venv+deps.
• Negative: a dependency on the uv binary on the host (it is not stdlib); anyone who does not have it must install it (pip install uv).

Alternatives Considered

pip + requirements.txt

Less deterministic, no modern lockfile resolver, slower.

Poetry / PDM

Valid but slower and heavier than uv; uv covers lock+venv+run with minimal overhead.