npm install vs npm ci: Why Your CI Pipeline Needs a Different Command Than Your Laptop

Copy a Dockerfile or GitHub Actions workflow from a tutorial and you’ll almost always see npm ci instead of the npm install you run locally every day. They look like they should be interchangeable — both install your dependencies — but they operate on package-lock.json and node_modules in fundamentally different ways, and using the wrong one in the wrong place is a common source of “works on my machine, fails in CI” bugs.

Which Command Should You Use?

What Each Command Actually Does

npm install

• Reads package.json to determine what’s needed.
• Resolves the newest versions allowed by your version ranges (^, ~, etc.) that are also compatible with what’s already in package-lock.json.
• Writes any changes back to package-lock.json and package.json if you’re adding/removing a package.
• Reuses your existing node_modules where possible instead of wiping it — generally faster for small, incremental changes.

npm install
npm install lodash          # adds a new dependency
npm install lodash@4.17.21  # installs a specific version

npm ci

• Requires a package-lock.json (or npm-shrinkwrap.json) to already exist — it errors out immediately if one is missing.
• Deletes the existing node_modules folder entirely before installing anything.
• Installs the exact versions listed in the lockfile — no resolution, no range-matching, no “close enough.”
• Fails immediately if package.json and package-lock.json are out of sync, rather than silently reconciling them.
• Never writes to package.json or package-lock.json under any circumstance.

npm ci

Side-by-Side Comparison

Why CI Pipelines Specifically Need npm ci

A CI pipeline’s whole job is to reproduce the exact same install every single time, regardless of which machine runs it or when. npm install is deliberately a little flexible — it can silently pick a newer patch version than what’s pinned if your ranges allow it, which is exactly the kind of small drift you don’t want in an automated pipeline. A build that passed yesterday could behave differently today for no code reason at all.

npm ci removes that flexibility on purpose. Because it installs precisely what’s locked and refuses to proceed on any mismatch, a failing npm ci step in your pipeline is actually useful signal — it means someone changed package.json without regenerating the lockfile, not that npm silently “fixed” the discrepancy for them.

package-lock.json Best Practices

• Always commit it. It’s not a build artifact — it’s what makes your install reproducible across machines and over time.
• Never edit it by hand. Let npm install regenerate it after you change package.json.
• Don’t .gitignore it “to avoid merge conflicts” — this trades a solvable annoyance for genuinely nondeterministic builds.
• Resolve lockfile merge conflicts by regenerating, not hand-editing: pull the latest package.json, delete the conflicted lockfile, run npm install again, and commit the clean result.
• Run npm ci locally before pushing if you want to catch sync issues before your pipeline does.

Troubleshooting Checklist

1. Getting a lockfile sync error in CI? Run npm install locally, confirm package-lock.json changed, and commit it.
2. CI install unexpectedly slow? Confirm you’re actually using npm ci and not npm install in your workflow file — this is a very common copy-paste mistake.
3. Getting different behavior locally vs. in CI with the “same” dependencies? Delete your local node_modules and run npm ci locally to match CI’s exact install.
4. Docker build cache not helping? Make sure you’re copying package.json and package-lock.json into the image and running npm ci before copying the rest of your source code, so the dependency layer only rebuilds when those two files change.
5. No package-lock.json in the repo at all? You’ll need npm install first to generate one — npm ci can’t bootstrap a project from nothing.

FAQ