1--- 2title: npm-ci 3section: 1 4description: Clean install a project 5--- 6 7### Synopsis 8 9```bash 10npm ci 11 12aliases: clean-install, ic, install-clean, isntall-clean 13``` 14 15### Description 16 17This command is similar to [`npm install`](/commands/npm-install), except 18it's meant to be used in automated environments such as test platforms, 19continuous integration, and deployment -- or any situation where you want 20to make sure you're doing a clean install of your dependencies. 21 22The main differences between using `npm install` and `npm ci` are: 23 24* The project **must** have an existing `package-lock.json` or 25 `npm-shrinkwrap.json`. 26* If dependencies in the package lock do not match those in `package.json`, 27 `npm ci` will exit with an error, instead of updating the package lock. 28* `npm ci` can only install entire projects at a time: individual 29 dependencies cannot be added with this command. 30* If a `node_modules` is already present, it will be automatically removed 31 before `npm ci` begins its install. 32* It will never write to `package.json` or any of the package-locks: 33 installs are essentially frozen. 34 35NOTE: If you create your `package-lock.json` file by running `npm install` 36with flags that can affect the shape of your dependency tree, such as 37`--legacy-peer-deps` or `--install-links`, you _must_ provide the same 38flags to `npm ci` or you are likely to encounter errors. An easy way to do 39this is to run, for example, 40`npm config set legacy-peer-deps=true --location=project` and commit the 41`.npmrc` file to your repo. 42 43### Example 44 45Make sure you have a package-lock and an up-to-date install: 46 47```bash 48$ cd ./my/npm/project 49$ npm install 50added 154 packages in 10s 51$ ls | grep package-lock 52``` 53 54Run `npm ci` in that project 55 56```bash 57$ npm ci 58added 154 packages in 5s 59``` 60 61Configure Travis CI to build using `npm ci` instead of `npm install`: 62 63```bash 64# .travis.yml 65install: 66- npm ci 67# keep the npm cache around to speed up installs 68cache: 69 directories: 70 - "$HOME/.npm" 71``` 72 73### Configuration 74 75#### `install-strategy` 76 77* Default: "hoisted" 78* Type: "hoisted", "nested", "shallow", or "linked" 79 80Sets the strategy for installing packages in node_modules. hoisted 81(default): Install non-duplicated in top-level, and duplicated as necessary 82within directory structure. nested: (formerly --legacy-bundling) install in 83place, no hoisting. shallow (formerly --global-style) only install direct 84deps at top-level. linked: (experimental) install in node_modules/.store, 85link in place, unhoisted. 86 87 88 89#### `legacy-bundling` 90 91* Default: false 92* Type: Boolean 93* DEPRECATED: This option has been deprecated in favor of 94 `--install-strategy=nested` 95 96Instead of hoisting package installs in `node_modules`, install packages in 97the same manner that they are depended on. This may cause very deep 98directory structures and duplicate package installs as there is no 99de-duplicating. Sets `--install-strategy=nested`. 100 101 102 103#### `global-style` 104 105* Default: false 106* Type: Boolean 107* DEPRECATED: This option has been deprecated in favor of 108 `--install-strategy=shallow` 109 110Only install direct dependencies in the top level `node_modules`, but hoist 111on deeper dependencies. Sets `--install-strategy=shallow`. 112 113 114 115#### `omit` 116 117* Default: 'dev' if the `NODE_ENV` environment variable is set to 118 'production', otherwise empty. 119* Type: "dev", "optional", or "peer" (can be set multiple times) 120 121Dependency types to omit from the installation tree on disk. 122 123Note that these dependencies _are_ still resolved and added to the 124`package-lock.json` or `npm-shrinkwrap.json` file. They are just not 125physically installed on disk. 126 127If a package type appears in both the `--include` and `--omit` lists, then 128it will be included. 129 130If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment 131variable will be set to `'production'` for all lifecycle scripts. 132 133 134 135#### `include` 136 137* Default: 138* Type: "prod", "dev", "optional", or "peer" (can be set multiple times) 139 140Option that allows for defining which types of dependencies to install. 141 142This is the inverse of `--omit=<type>`. 143 144Dependency types specified in `--include` will not be omitted, regardless of 145the order in which omit/include are specified on the command-line. 146 147 148 149#### `strict-peer-deps` 150 151* Default: false 152* Type: Boolean 153 154If set to `true`, and `--legacy-peer-deps` is not set, then _any_ 155conflicting `peerDependencies` will be treated as an install failure, even 156if npm could reasonably guess the appropriate resolution based on non-peer 157dependency relationships. 158 159By default, conflicting `peerDependencies` deep in the dependency graph will 160be resolved using the nearest non-peer dependency specification, even if 161doing so will result in some packages receiving a peer dependency outside 162the range set in their package's `peerDependencies` object. 163 164When such an override is performed, a warning is printed, explaining the 165conflict and the packages involved. If `--strict-peer-deps` is set, then 166this warning is treated as a failure. 167 168 169 170#### `foreground-scripts` 171 172* Default: `false` unless when using `npm pack` or `npm publish` where it 173 defaults to `true` 174* Type: Boolean 175 176Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) 177scripts for installed packages in the foreground process, sharing standard 178input, output, and error with the main npm process. 179 180Note that this will generally make installs run slower, and be much noisier, 181but can be useful for debugging. 182 183 184 185#### `ignore-scripts` 186 187* Default: false 188* Type: Boolean 189 190If true, npm does not run scripts specified in package.json files. 191 192Note that commands explicitly intended to run a particular script, such as 193`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` 194will still run their intended script if `ignore-scripts` is set, but they 195will *not* run any pre- or post-scripts. 196 197 198 199#### `audit` 200 201* Default: true 202* Type: Boolean 203 204When "true" submit audit reports alongside the current npm command to the 205default registry and all registries configured for scopes. See the 206documentation for [`npm audit`](/commands/npm-audit) for details on what is 207submitted. 208 209 210 211#### `bin-links` 212 213* Default: true 214* Type: Boolean 215 216Tells npm to create symlinks (or `.cmd` shims on Windows) for package 217executables. 218 219Set to false to have it not do this. This can be used to work around the 220fact that some file systems don't support symlinks, even on ostensibly Unix 221systems. 222 223 224 225#### `fund` 226 227* Default: true 228* Type: Boolean 229 230When "true" displays the message at the end of each `npm install` 231acknowledging the number of dependencies looking for funding. See [`npm 232fund`](/commands/npm-fund) for details. 233 234 235 236#### `dry-run` 237 238* Default: false 239* Type: Boolean 240 241Indicates that you don't want npm to make any changes and that it should 242only report what it would have done. This can be passed into any of the 243commands that modify your local installation, eg, `install`, `update`, 244`dedupe`, `uninstall`, as well as `pack` and `publish`. 245 246Note: This is NOT honored by other network related commands, eg `dist-tags`, 247`owner`, etc. 248 249 250 251#### `workspace` 252 253* Default: 254* Type: String (can be set multiple times) 255 256Enable running a command in the context of the configured workspaces of the 257current project while filtering by running only the workspaces defined by 258this configuration option. 259 260Valid values for the `workspace` config are either: 261 262* Workspace names 263* Path to a workspace directory 264* Path to a parent workspace directory (will result in selecting all 265 workspaces within that folder) 266 267When set for the `npm init` command, this may be set to the folder of a 268workspace which does not yet exist, to create the folder and set it up as a 269brand new workspace within the project. 270 271This value is not exported to the environment for child processes. 272 273#### `workspaces` 274 275* Default: null 276* Type: null or Boolean 277 278Set to true to run the command in the context of **all** configured 279workspaces. 280 281Explicitly setting this to false will cause commands like `install` to 282ignore workspaces altogether. When not set explicitly: 283 284- Commands that operate on the `node_modules` tree (install, update, etc.) 285will link workspaces into the `node_modules` folder. - Commands that do 286other things (test, exec, publish, etc.) will operate on the root project, 287_unless_ one or more workspaces are specified in the `workspace` config. 288 289This value is not exported to the environment for child processes. 290 291#### `include-workspace-root` 292 293* Default: false 294* Type: Boolean 295 296Include the workspace root when workspaces are enabled for a command. 297 298When false, specifying individual workspaces via the `workspace` config, or 299all workspaces via the `workspaces` flag, will cause npm to operate only on 300the specified workspaces, and not on the root project. 301 302This value is not exported to the environment for child processes. 303 304#### `install-links` 305 306* Default: false 307* Type: Boolean 308 309When set file: protocol dependencies will be packed and installed as regular 310dependencies instead of creating a symlink. This option has no effect on 311workspaces. 312 313 314 315### See Also 316 317* [npm install](/commands/npm-install) 318* [package-lock.json](/configuring-npm/package-lock-json) 319