# Lockfiles and Version Pinning

> 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:** [Code Editors and Package Managers](https://learn.benibix.com/learn/development-tools)  
**Time:** 13 min

**After this lesson you can:**

- Explain what a lockfile records
- Read a pinned version and a range
- Get out of a version clash

## 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.

![An app box at the top needs two packages, A and B. A asks for package C at version 1, and B asks for C at version 2. Both arrows meet at one box for C, marked as a clash, since only one version fits. At the bottom, a pinned line reads react 18.3.1, beside a range line that reads ^18.3.1 and allows any later 18.x version.](https://learn.benibix.com/diagrams/dev5-version-conflict.svg)

### 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.

**Words in this lesson:** [Lockfile](https://learn.benibix.com/term/development/lockfile), [Version Pinning](https://learn.benibix.com/term/development/version-pinning), [Dependency Hell](https://learn.benibix.com/term/development/dependency-hell)

**Question:** Should I commit the lockfile to Git?

**Answer:** Yes, so every install gets the same versions. The lockfile records the exact versions you tested. With it in Git, a teammate or a server installs the very same set.

---

Source: https://learn.benibix.com/learn/development-tools/lockfiles-and-version-pinning
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-19
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
