Principle:PrefectHQ Prefect Dependency Lockfile Management
| Knowledge Sources | |
|---|---|
| Domains | Dependency_Management, Build_System, DevOps |
| Last Updated | 2026-02-09 22:00 GMT |
Overview
Principle of pinning exact dependency versions via lock files to ensure deterministic, reproducible builds across all environments.
Description
Dependency Lockfile Management is the practice of recording the exact resolved version, integrity hash, and dependency tree for every direct and transitive package dependency. While `package.json` (or `pyproject.toml`) declares acceptable version ranges, the lock file records the specific version that was actually resolved during installation. This guarantees that every developer, CI runner, and production environment uses identical dependency versions, eliminating "works on my machine" problems caused by version drift. Lock files should always be committed to version control and never edited manually.
Usage
Apply this principle to any project with external dependencies, especially when multiple environments (development, CI, staging, production) must produce identical builds. Use `npm ci` (not `npm install`) in CI environments to enforce strict lock file adherence.
Theoretical Basis
The core mechanism is deterministic dependency resolution:
- Declare ranges: Package manifest specifies acceptable version ranges (e.g., `^5.90.20`)
- Resolve once: Package manager resolves ranges to exact versions and records them
- Lock results: Write resolved versions, integrity hashes, and tree structure to lock file
- Replay everywhere: Other environments read the lock file and install exact versions
- Verify integrity: Hash comparison ensures downloaded packages match locked expectations
Pseudo-code Logic:
# Abstract dependency resolution
manifest = read_package_manifest() # Version ranges
lock = read_lock_file() # Exact versions (if exists)
if lock.is_valid_for(manifest):
install_exact_versions(lock) # Deterministic install
else:
resolved = resolve_ranges(manifest, registry)
install_exact_versions(resolved)
write_lock_file(resolved) # Update lock file