uv locked vs frozen: the missing dependency test

Description and use

In CI pipelines, uv sync --frozen can succeed even when a new dependency is added but the lockfile is stale. Use uv sync --locked to catch mismatches and avoid silent failures.

Problem

CI may falsely pass when a new dependency is added but the lockfile is not updated, because uv sync --frozen skips the lockfile freshness check.

Outcome

Using uv sync --locked in CI prevents silent failures caused by stale lockfiles, ensuring that added dependencies are always reflected in the environment.

Workflow

• Generate initial lockfile with uv lock
• Add a new dependency to pyproject.toml without updating the lockfile
• Run uv sync --locked to verify lockfile freshness (should fail)
• Run uv sync --frozen to see that it succeeds but the dependency is missing
• Run uv sync to update the lockfile and install the new dependency
• Run uv lock --check to confirm the updated lockfile matches the manifest

Evidence

uv sync --locked rejects the stale lockfile. Its bytes did not change.

Source

uv sync --frozen accepts the old lockfile. The new dependency was absent.

Source