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