codekingpro/portable-devtools

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