Lockfiles and Version Pinning
Level 4 · Other people's code
How a lockfile makes every install the same, what the ^ in a version means, and how pinning helps. What dependency hell is, and how to stay out of it.
Course contentsLesson 10 of 13
Level 1 · The editor
Level 2 · Checking and fixing code
Level 3 · Trying code out
Level 4 · Other people's code
Level 5 · Building the project
After this lesson you can
- Explain what a lockfile records
- Read a pinned version and a range
- Get out of a version clash
13 mincovers 3 glossary entries
Worth reading first: Yarn, pnpm, Cargo and Homebrew
Why the same project installs the same way twice
A lockfile lists the exact version of each package your project uses, and of the packages those need. npm's lockfile is called package-lock.json. A range like ^18.3.1 lets in any 18 version from 18.3.1 up. The lockfile writes down the one you got, so each install matches.
Without a lockfile, two installs a week apart can differ. A package you depend on ships a new version on Tuesday. Your teammate installs on Wednesday and gets it, and you do not. Now the same code acts in two ways, and nobody changed a line.
The lockfile goes into Git with your code. On a test server, npm ci installs just what the lockfile says. It stops with an error if the lockfile and the list of needs do not match. It never changes either file.
Version pinning means asking for one exact version, such as 18.3.1 with no ^ in front. A pin never changes until you change it. The cost is that fixes do not arrive on their own, so you update pins by hand or let a bot open a change for each one.
Dependency hell is what happens when packages need versions that cannot all fit. Package A needs version 1 of package C. Package B needs version 2. If only one copy of C is allowed, the install fails, or one part breaks at run time.
The way out is rarely clever. Update A or B to a version that agrees on C. If neither has one, replace one of them. Keeping the list of packages short is the best defence, because each one you drop is a clash that cannot happen.
Two mistakes cause most of the pain. One is deleting the lockfile to make an error go away, which throws away the versions you tested. The other is forcing an install past a clash with a flag that skips the check. The clash is still there, and it shows up later as a bug.
"dependencies": {
"react": "18.3.1",
"lodash": "^4.17.21"
}Worked example
Jack's app works only on his laptop
The words for this lesson3
Check yourself
Should I commit the lockfile to Git?
Finished this lesson?
Marking it complete also marks its 3 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.