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#### `strict-peer-deps` 136 137* Default: false 138* Type: Boolean 139 140If set to `true`, and `--legacy-peer-deps` is not set, then _any_ 141conflicting `peerDependencies` will be treated as an install failure, even 142if npm could reasonably guess the appropriate resolution based on non-peer 143dependency relationships. 144 145By default, conflicting `peerDependencies` deep in the dependency graph will 146be resolved using the nearest non-peer dependency specification, even if 147doing so will result in some packages receiving a peer dependency outside 148the range set in their package's `peerDependencies` object. 149 150When such an override is performed, a warning is printed, explaining the 151conflict and the packages involved. If `--strict-peer-deps` is set, then 152this warning is treated as a failure. 153 154 155 156#### `foreground-scripts` 157 158* Default: false 159* Type: Boolean 160 161Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) 162scripts for installed packages in the foreground process, sharing standard 163input, output, and error with the main npm process. 164 165Note that this will generally make installs run slower, and be much noisier, 166but can be useful for debugging. 167 168 169 170#### `ignore-scripts` 171 172* Default: false 173* Type: Boolean 174 175If true, npm does not run scripts specified in package.json files. 176 177Note that commands explicitly intended to run a particular script, such as 178`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` 179will still run their intended script if `ignore-scripts` is set, but they 180will *not* run any pre- or post-scripts. 181 182 183 184#### `audit` 185 186* Default: true 187* Type: Boolean 188 189When "true" submit audit reports alongside the current npm command to the 190default registry and all registries configured for scopes. See the 191documentation for [`npm audit`](/commands/npm-audit) for details on what is 192submitted. 193 194 195 196#### `bin-links` 197 198* Default: true 199* Type: Boolean 200 201Tells npm to create symlinks (or `.cmd` shims on Windows) for package 202executables. 203 204Set to false to have it not do this. This can be used to work around the 205fact that some file systems don't support symlinks, even on ostensibly Unix 206systems. 207 208 209 210#### `fund` 211 212* Default: true 213* Type: Boolean 214 215When "true" displays the message at the end of each `npm install` 216acknowledging the number of dependencies looking for funding. See [`npm 217fund`](/commands/npm-fund) for details. 218 219 220 221#### `dry-run` 222 223* Default: false 224* Type: Boolean 225 226Indicates that you don't want npm to make any changes and that it should 227only report what it would have done. This can be passed into any of the 228commands that modify your local installation, eg, `install`, `update`, 229`dedupe`, `uninstall`, as well as `pack` and `publish`. 230 231Note: This is NOT honored by other network related commands, eg `dist-tags`, 232`owner`, etc. 233 234 235 236#### `workspace` 237 238* Default: 239* Type: String (can be set multiple times) 240 241Enable running a command in the context of the configured workspaces of the 242current project while filtering by running only the workspaces defined by 243this configuration option. 244 245Valid values for the `workspace` config are either: 246 247* Workspace names 248* Path to a workspace directory 249* Path to a parent workspace directory (will result in selecting all 250 workspaces within that folder) 251 252When set for the `npm init` command, this may be set to the folder of a 253workspace which does not yet exist, to create the folder and set it up as a 254brand new workspace within the project. 255 256This value is not exported to the environment for child processes. 257 258#### `workspaces` 259 260* Default: null 261* Type: null or Boolean 262 263Set to true to run the command in the context of **all** configured 264workspaces. 265 266Explicitly setting this to false will cause commands like `install` to 267ignore workspaces altogether. When not set explicitly: 268 269- Commands that operate on the `node_modules` tree (install, update, etc.) 270will link workspaces into the `node_modules` folder. - Commands that do 271other things (test, exec, publish, etc.) will operate on the root project, 272_unless_ one or more workspaces are specified in the `workspace` config. 273 274This value is not exported to the environment for child processes. 275 276#### `include-workspace-root` 277 278* Default: false 279* Type: Boolean 280 281Include the workspace root when workspaces are enabled for a command. 282 283When false, specifying individual workspaces via the `workspace` config, or 284all workspaces via the `workspaces` flag, will cause npm to operate only on 285the specified workspaces, and not on the root project. 286 287This value is not exported to the environment for child processes. 288 289#### `install-links` 290 291* Default: false 292* Type: Boolean 293 294When set file: protocol dependencies will be packed and installed as regular 295dependencies instead of creating a symlink. This option has no effect on 296workspaces. 297 298 299 300### See Also 301 302* [npm install](/commands/npm-install) 303* [package-lock.json](/configuring-npm/package-lock-json) 304