Dependency Lock File

A dependency declaration states what a project requires, often allowing a range of versions. A lock file records a resolved dependency graph, including indirect dependencies and information needed to select concrete packages. The declaration expresses constraints; the lock captures a resolution that can be reviewed and reused.

A lock is not necessarily one identical package list for every machine. A universal lock can contain conditional versions or artifacts for different Python versions, operating systems, and architectures. Selected dependency groups and extras also affect installation. Record the interpreter and target platform alongside the lock when comparing a test environment with production.

In uv, –locked requires the existing lock to remain consistent with project metadata and fails instead of updating it. Plain synchronization can refresh the lock when required. The –frozen option uses the lock without checking that freshness condition. A newly released package does not by itself make a lock stale: staleness here means disagreement with the project’s declared requirements, not age.

For an intended upgrade, update the declaration or resolution, inspect the changed dependency graph, and rerun relevant checks before committing it. A lock does not prove the transformation is correct, freeze remote input data, or capture every operating-system dependency. Build dependencies can also need separate control when reproducing a wheel matters.

Reference: uv locking and syncing. For worked examples, see Python for Data Engineers.