Skip to content
BENIBIX Learn

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

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.

json
"dependencies": {
  "react": "18.3.1",
  "lodash": "^4.17.21"
}
react is pinned to one version. lodash may move to any later 4.x version, and the lockfile records which one.
Two packages want two versions of a third, and only one fits. Below, a pin names one version and a range allows newer ones.

Worked example

Jack's app works only on his laptop

Jack's app runs on his laptop but fails on the test server. The project has no lockfile, so the server installed a date package 2 versions newer than his.

He commits a lockfile and switches the server to npm ci. From then on, both machines install the same 214 packages.

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.