Use npm ci for Clean, Reproducible Dependency Installs

When you run npm install in a Node.js project, the result can vary between machines and over time. The package.json file typically specifies semver ranges like ^18.2.0, so npm may install a newer patch or minor version that still satisfies the range. Worse, npm install can silently update package-lock.json, introducing changes that make your CI build differ from your local environment. The command npm ci solves this by installing dependencies exactly as recorded in the lockfile, without modifying it.

This guide walks you through using npm ci for deterministic dependency installation, including prerequisites, the exact steps, how to verify the result, and what to do when something goes wrong.

What npm ci Does Differently

npm ci (introduced in npm 5.7.0) performs a clean install:

• Deletes the existing node_modules directory entirely.
• Installs every package exactly as specified in package-lock.json — no version resolution, no range matching.
• Does not modify package-lock.json or package.json.
• Is generally faster than npm install in a fresh CI environment because it skips dependency resolution and uses the lockfile directly.

This makes it the recommended command for CI/CD pipelines, deployment scripts, and any situation where you need a reproducible build.

Prerequisites

Before you run npm ci, ensure the following:

• Node.js and npm installed — npm version 5.7.0 or higher. Check with npm --version.
• A package-lock.json file in your project root. This is generated automatically by npm install and should be committed to version control.
• The lockfile is in sync with package.json. If you've added, removed, or changed a dependency in package.json without updating the lockfile, npm ci will fail with an error like npm ci can only install packages when your package.json and package-lock.json are in sync.

If you don't have a lockfile yet, run npm install once to generate it, then commit it.

Procedure: Running npm ci

Open a terminal in your project root (where package.json lives) and run:

npm ci

That's it. npm will:

1. Remove the existing node_modules folder (if present).
2. Install all dependencies listed in package-lock.json with exact versions.
3. Exit with code 0 on success.

For a dry run that checks for errors without touching node_modules, use:

npm ci --dry-run

This simulates the install and reports any issues (like an out-of-sync lockfile) without modifying your project.

Example: CI Pipeline Step

In a GitHub Actions workflow, you might have:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci
      - run: npm test

The npm ci step ensures every build uses the exact dependency versions from the lockfile.

Expected Checks and Verification

After running npm ci, verify the install succeeded:

1. Check the exit code — it should be 0. In a shell, you can echo it with echo $? (Linux/macOS) or echo %ERRORLEVEL% (Windows).
2. Confirm node_modules exists and contains your dependencies: ls node_modules (or dir on Windows).
3. Validate the dependency tree with npm ls. This command prints the installed tree and exits with an error if any package is missing or has an invalid version. A clean output means everything matches the lockfile.
4. Ensure the lockfile was not modified — in a version-controlled project, run git status. You should see no changes to package-lock.json or package.json. If you see modifications, something else (like a postinstall script) altered them.

For a thorough reproducibility check, run npm ci in a clean environment such as a Docker container or a fresh CI job. Compare the output of npm ls across runs — it should be identical.

Recovery Options When npm ci Fails

The most common failure is an out-of-sync lockfile. Here's how to fix it:

• Lockfile out of sync with package.json: Run npm install to update the lockfile to match your package.json. Then commit the updated lockfile and rerun npm ci. Do not edit the lockfile manually.
• Missing lockfile: If you don't have a package-lock.json, run npm install once to generate it. Commit it immediately.
• Corrupted node_modules: Since npm ci deletes the folder, a corrupted install is usually resolved by simply rerunning npm ci. If that fails, delete node_modules manually (rm -rf node_modules on Linux/macOS, rmdir /s node_modules on Windows) and run npm ci again.
• npm version too old: If you're on npm 5.6 or earlier, upgrade npm with npm install -g npm@latest.

Remember that npm ci is destructive to node_modules — it always removes it first. If you have local modifications inside node_modules (which you shouldn't, since it's generated), they will be lost. For local development with frequent dependency changes, npm install is still the right tool because it updates the lockfile and installs incrementally.

npm ci vs npm install: Quick Comparison

Operation	npm install	npm ci
Reads package.json	Yes	No (uses lockfile)
Modifies package-lock.json	Yes (unless --no-save)	Never
Removes node_modules first	No	Yes
Version resolution	Uses ranges	Exact from lockfile
Best for	Local development	CI/CD, reproducible builds

Limitations to Keep in Mind

• npm ci requires a lockfile. If your project uses yarn.lock or pnpm-lock.yaml, this command won't work — use the corresponding package manager's equivalent.
• The first run in a clean environment is not necessarily faster than npm install because it downloads all packages from scratch. The speed advantage appears in repeated builds with cached packages.
• If your project uses npm workspaces, npm ci installs all workspace dependencies as defined in the lockfile, which is correct for monorepos.

By adopting npm ci in your automated workflows, you eliminate a whole class of "works on my machine" problems. The lockfile becomes the single source of truth, and every build — whether on your laptop, in CI, or in production — uses identical dependency versions.