npm install vs npm ci — What's the Difference?

npm install resolves versions from package.json and may update package-lock.json; npm ci installs exactly what the lockfile says, deletes node_modules first, and fails if they disagree. Use npm ci in CI and deployments.

The concept

install is for development: it adds packages and keeps the lockfile in sync. ci is for reproducibility: same lockfile, same tree, every time.

ci is usually faster in clean environments and never writes to package.json or the lockfile.

Behaviour

npm install npm ci

reads package.json+lock lock only

modifies lock maybe never

node_modules reuses deletes first

mismatch updates errors

Practical examples

Development

npm install lodash

CI and Docker

npm ci --omit=dev

GitHub Actions cache

- uses: actions/setup-node@v4
  with: { node-version: 20, cache: npm }
- run: npm ci

Common mistakes

Using npm install in CI and getting different versions.
Not committing package-lock.json.
Hand-editing package.json without updating the lockfile, then seeing npm ci fail.

Key takeaways

install = flexible, ci = exact.
Commit the lockfile.
Use ci for builds.

FAQ

Why does npm ci fail?

package.json and the lockfile disagree; run npm install locally and commit.

Does ci need a lockfile?

Yes.