npm-ci

Install project dependencies from package-lock.json or npm-shrinkwrap.json

$ npm ci

$ npm ci --omit [dev|optional|peer]

$ npm ci --ignore-scripts

npm ci [options]

--prefix <path>
    The directory to resolve relative paths for when looking up package.json and node_modules. Often used to specify an alternate installation location.

--production
--omit=dev
    Install only production dependencies. Development dependencies are skipped.

--no-optional
    Prevent optional dependencies from being installed.

--ignore-scripts
    Do not run pre/post install scripts defined in package.json. This can be useful for security or to speed up installations.

--loglevel <level>
    Set the level of logging messages to display. Common levels include silent, error, warn, info, http, verbose, silly.

--json
    Output raw JSON data for machine readability, especially useful for programmatic consumption of command results.

--dry-run
    Simulate the installation without actually making any changes to the file system. Shows what npm ci would do.

--registry <url>
    Specify a custom npm registry URL to fetch packages from.

--legacy-peer-deps
    Permit the installation to proceed even if peer dependency conflicts are found. This can help bypass strict peer dependency checks that might otherwise block installations.

npm ci is explicitly designed for automated environments like Continuous Integration/Continuous Deployment (CI/CD) pipelines. It ensures that a project's dependencies are installed exactly as defined in the package-lock.json or npm-shrinkwrap.json file. Unlike npm install, npm ci will first remove any existing node_modules directory before performing a fresh, clean installation. This guarantees a consistent and reproducible dependency state across different environments and runs, preventing partial updates or unintended dependency upgrades.

It is generally faster than npm install in CI scenarios because it skips dependency resolution and directly installs from the lock file. It prioritizes strict adherence to the lock file, making it ideal for build processes where exact dependency versions are critical for reliability.

Requires a package-lock.json or npm-shrinkwrap.json file to be present in the project root.
The package-lock.json must be consistent with package.json. If discrepancies are found (e.g., a dependency in package.json is not in the lock file), npm ci will fail.
npm ci will always delete the existing node_modules directory before installing, ensuring a clean slate. This means any local changes or uncommitted modules in node_modules will be lost.
It will never modify package.json or package-lock.json.

npm ci is designed to fail explicitly if a package-lock.json is missing or if it's out of sync with package.json. This strict behavior provides immediate feedback on potential dependency inconsistencies, aiding in debugging and maintaining project integrity.

In many CI scenarios, npm ci is significantly faster than npm install. This is because it skips the dependency resolution phase (as it trusts the lock file entirely) and directly installs packages, leading to quicker build times.

npm ci was introduced in npm v5.7.0 in January 2018. Its development was driven by the need for a more deterministic, reliable, and faster installation method specifically tailored for automated build and deployment environments (CI/CD). Prior to npm ci, npm install was often used, but its behavior of potentially modifying package-lock.json or being less strict about exact versions could lead to inconsistencies across different build runs. npm ci provides a strict contract, ensuring exact reproducibility.

npm-install(1), npm-update(1), npm-prune(1), npm-run-script(1)