From the official documentation for npm ci:
In short, the main differences between using npm install and npm ci are:
- The project must have an existing package-lock.json or npm-shrinkwrap.json.
- If dependencies in the package lock do not match those in package.json, npm ci will exit with an error, instead of updating the package lock.
- npm ci can only install entire projects at a time: individual dependencies cannot be added with this command.
- If a node_modules is already present, it will be automatically removed before npm ci begins its install.
- It will never write to package.json or any of the package-locks: installs are essentially frozen.
Essentially,
npm install
reads package.json
to create a list of dependencies and uses package-lock.json
to inform which versions of these dependencies to install. If a dependency is not in package-lock.json
it will be added by npm install
.
npm ci
(also known as Clean Install) is meant to be used in automated environments — such as test platforms, continuous integration, and deployment — or, any situation where you want to make sure you’re doing a clean install of your dependencies.
It installs dependencies directly from package-lock.json
and uses package.json
only to validate that there are no mismatched versions. If any dependencies are missing or have incompatible versions, it will throw an error.
Use npm install
to add new dependencies, and to update dependencies on a project. Usually, you would use it during development after pulling changes that update the list of dependencies but it may be a good idea to use npm ci
in this case.
Use npm ci
if you need a deterministic, repeatable build. For example during continuous integration, automated jobs, etc. and when installing dependencies for the first time, instead of npm install
.
npm install
- Installs a package and all its dependencies.
- Dependencies are driven by
npm-shrinkwrap.json
andpackage-lock.json
(in that order). - without arguments: installs dependencies of a local module.
- Can install global packages.
- Will install any missing dependencies in
node_modules
. - It may write to
package.json
orpackage-lock.json
.- When used with an argument (
npm i packagename
) it may write topackage.json
to add or update the dependency. - when used without arguments, (
npm i
) it may write topackage-lock.json
to lock down the version of some dependencies if they are not already in this file.
- When used with an argument (
npm ci
- Requires at least npm v5.7.1.
- Requires
package-lock.json
ornpm-shrinkwrap.json
to be present. - Throws an error if dependencies from these two files don’t match
package.json
. - Removes
node_modules
and install all dependencies at once. - It never writes to
package.json
orpackage-lock.json
.
Algorithm
While npm ci
generates the entire dependency tree from package-lock.json
or npm-shrinkwrap.json
, npm install
updates the contents of node_modules
using the following algorithm (source):
load the existing node_modules tree from disk clone the tree fetch the package.json and assorted metadata and add it to the clone walk the clone and add any missing dependencies dependencies will be added as close to the top as is possible without breaking any other modules compare the original tree with the cloned tree and make a list of actions to take to convert one to the other execute all of the actions, deepest first kinds of actions are install, update, remove and move