1 ---
2 title: npm-install
3 section: 1
4 description: Install a package
5 github_repo: npm/cli
6 github_branch: release/v10
7 github_path: docs/lib/content/commands/npm-install.md
8 redirect_from:
9 - /cli-documentation/v10/cli-commands/install
10 - /cli-documentation/v10/cli-commands/npm-install
11 - /cli-documentation/v10/commands/install
12 - /cli-documentation/v10/commands/npm-install
13 - /cli-documentation/v10/install
14 - /cli-documentation/v10/npm-install
15 - /cli/v10/cli-commands/install
16 - /cli/v10/cli-commands/npm-install
17 - /cli/v10/commands/install
18 - /cli/v10/install
19 - /cli/v10/npm-install
20 ---
21
22 ### Synopsis
23
24 ```bash
25 npm install [<package-spec> ...]
26
27 aliases: add, i, in, ins, inst, insta, instal, isnt, isnta, isntal, isntall
28 ```
29
30 ### Description
31
32 This command installs a package and any packages that it depends on. If the package has a package-lock, or an npm shrinkwrap file, or a yarn lock file, the installation of dependencies will be driven by that, respecting the following order of precedence:
33
34 - `npm-shrinkwrap.json`
35 - `package-lock.json`
36 - `yarn.lock`
37
38 See [package-lock.json](/cli/v10/configuring-npm/package-lock-json) and [`npm shrinkwrap`](/cli/v10/commands/npm-shrinkwrap).
39
40 A `package` is:
41
42 - a) a folder containing a program described by a [`package.json`](/cli/v10/configuring-npm/package-json) file
43 - b) a gzipped tarball containing (a)
44 - c) a url that resolves to (b)
45 - d) a `<name>@<version>` that is published on the registry (see [`registry`](/cli/v10/using-npm/registry)) with (c)
46 - e) a `<name>@<tag>` (see [`npm dist-tag`](/cli/v10/commands/npm-dist-tag)) that points to (d)
47 - f) a `<name>` that has a "latest" tag satisfying (e)
48 - g) a `<git remote url>` that resolves to (a)
49
50 Even if you never publish your package, you can still get a lot of benefits of using npm if you just want to write a node program (a), and perhaps if you also want to be able to easily install it elsewhere after packing it up into a tarball (b).
51
52 - `npm install` (in a package directory, no arguments):
53
54 Install the dependencies to the local `node_modules` folder.
55
56 In global mode (ie, with `-g` or `--global` appended to the command), it installs the current package context (ie, the current working directory) as a global package.
57
58 By default, `npm install` will install all modules listed as dependencies in [`package.json`](/cli/v10/configuring-npm/package-json).
59
60 With the `--production` flag (or when the `NODE_ENV` environment variable is set to `production`), npm will not install modules listed in `devDependencies`. To install all modules listed in both `dependencies` and `devDependencies` when `NODE_ENV` environment variable is set to `production`, you can use `--production=false`.
61
62 > NOTE: The `--production` flag has no particular meaning when adding a dependency to a project.
63
64 - `npm install <folder>`:
65
66 If `<folder>` sits inside the root of your project, its dependencies will be installed and may be hoisted to the top-level `node_modules` as they would for other types of dependencies. If `<folder>` sits outside the root of your project, _npm will not install the package dependencies_ in the directory `<folder>`, but it will create a symlink to `<folder>`.
67
68 > NOTE: If you want to install the content of a directory like a package from the registry instead of creating a link, you would need to use the `--install-links` option.
69
70 Example:
71
72 ```bash
73 npm install ../../other-package --install-links
74 npm install ./sub-package
75 ```
76
77 - `npm install <tarball file>`:
78
79 Install a package that is sitting on the filesystem. Note: if you just want to link a dev directory into your npm root, you can do this more easily by using [`npm link`](/cli/v10/commands/npm-link).
80
81 Tarball requirements:
82
83 - The filename _must_ use `.tar`, `.tar.gz`, or `.tgz` as the extension.
84 - The package contents should reside in a subfolder inside the tarball (usually it is called `package/`). npm strips one directory layer when installing the package (an equivalent of `tar x --strip-components=1` is run).
85 - The package must contain a `package.json` file with `name` and `version` properties.
86
87 Example:
88
89 ```bash
90 npm install ./package.tgz
91 ```
92
93 - `npm install <tarball url>`:
94
95 Fetch the tarball url, and then install it. In order to distinguish between this and other options, the argument must start with "http://" or "https://"
96
97 Example:
98
99 ```bash
100 npm install https://github.com/indexzero/forever/tarball/v0.5.6
101 ```
102
103 - `npm install [<@scope>/]<name>`:
104
105 Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See [`config`](/cli/v10/using-npm/config#tag). The config's default value is `latest`.)
106
107 In most cases, this will install the version of the modules tagged as `latest` on the npm registry.
108
109 Example:
110
111 ```bash
112 npm install sax
113 ```
114
115 `npm install` saves any specified packages into `dependencies` by default. Additionally, you can control where and how they get saved with some additional flags:
116
117 - `-P, --save-prod`: Package will appear in your `dependencies`. This is the default unless `-D` or `-O` are present.
118
119 - `-D, --save-dev`: Package will appear in your `devDependencies`.
120
121 - `--save-peer`: Package will appear in your `peerDependencies`.
122
123 - `-O, --save-optional`: Package will appear in your `optionalDependencies`.
124
125 - `--no-save`: Prevents saving to `dependencies`.
126
127 When using any of the above options to save dependencies to your package.json, there are two additional, optional flags:
128
129 - `-E, --save-exact`: Saved dependencies will be configured with an exact version rather than using npm's default semver range operator.
130
131 - `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list.
132
133 Further, if you have an `npm-shrinkwrap.json` or `package-lock.json` then it will be updated as well.
134
135 `<scope>` is optional. The package will be downloaded from the registry associated with the specified scope. If no registry is associated with the given scope the default registry is assumed. See [`scope`](/cli/v10/using-npm/scope).
136
137 Note: if you do not include the @-symbol on your scope name, npm will interpret this as a GitHub repository instead, see below. Scopes names must also be followed by a slash.
138
139 Examples:
140
141 ```bash
142 npm install sax
143 npm install githubname/reponame
144 npm install @myorg/privatepackage
145 npm install node-tap --save-dev
146 npm install dtrace-provider --save-optional
147 npm install readable-stream --save-exact
148 npm install ansi-regex --save-bundle
149 ```
150
151 - `npm install <alias>@npm:<name>`:
152
153 Install a package under a custom alias. Allows multiple versions of a same-name package side-by-side, more convenient import names for packages with otherwise long ones, and using git forks replacements or forked npm packages as replacements. Aliasing works only on your project and does not rename packages in transitive dependencies. Aliases should follow the naming conventions stated in [`validate-npm-package-name`](https://www.npmjs.com/package/validate-npm-package-name#naming-rules).
154
155 Examples:
156
157 ```bash
158 npm install my-react@npm:react
159 npm install jquery2@npm:jquery@2
160 npm install jquery3@npm:jquery@3
161 npm install npa@npm:npm-package-arg
162 ```
163
164 - `npm install [<@scope>/]<name>@<tag>`:
165
166 Install the version of the package that is referenced by the specified tag. If the tag does not exist in the registry data for that package, then this will fail.
167
168 Example:
169
170 ```bash
171 npm install sax@latest
172 npm install @myorg/mypackage@latest
173 ```
174
175 - `npm install [<@scope>/]<name>@<version>`:
176
177 Install the specified version of the package. This will fail if the version has not been published to the registry.
178
179 Example:
180
181 ```bash
182 npm install sax@0.1.1
183 npm install @myorg/privatepackage@1.5.0
184 ```
185
186 - `npm install [<@scope>/]<name>@<version range>`:
187
188 Install a version of the package matching the specified version range. This will follow the same rules for resolving dependencies described in [`package.json`](/cli/v10/configuring-npm/package-json).
189
190 Note that most version ranges must be put in quotes so that your shell will treat it as a single argument.
191
192 Example:
193
194 ```bash
195 npm install sax@">=0.1.0 <0.2.0"
196 npm install @myorg/privatepackage@"16 - 17"
197 ```
198
199 - `npm install <git remote url>`:
200
201 Installs the package from the hosted git provider, cloning it with `git`. For a full git remote url, only that URL will be attempted.
202
203 ```bash
204 <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
205 ```
206
207 `<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`, or `git+file`.
208
209 If `#<commit-ish>` is provided, it will be used to clone exactly that commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is specified, then the default branch of the repository is used.
210
211 If the repository makes use of submodules, those submodules will be cloned as well.
212
213 If the package being installed contains a `prepare` script, its `dependencies` and `devDependencies` will be installed, and the prepare script will be run, before the package is packaged and installed.
214
215 The following git environment variables are recognized by npm and will be added to the environment when running git:
216
217 - `GIT_ASKPASS`
218 - `GIT_EXEC_PATH`
219 - `GIT_PROXY_COMMAND`
220 - `GIT_SSH`
221 - `GIT_SSH_COMMAND`
222 - `GIT_SSL_CAINFO`
223 - `GIT_SSL_NO_VERIFY`
224
225 See the git man page for details.
226
227 Examples:
228
229 ```bash
230 npm install git+ssh://git@github.com:npm/cli.git#v1.0.27
231 npm install git+ssh://git@github.com:npm/cli#pull/273
232 npm install git+ssh://git@github.com:npm/cli#semver:^5.0
233 npm install git+https://isaacs@github.com/npm/cli.git
234 npm install git://github.com/npm/cli.git#v1.0.27
235 GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git
236 ```
237
238 - `npm install <githubname>/<githubrepo>[#<commit-ish>]`:
239 - `npm install github:<githubname>/<githubrepo>[#<commit-ish>]`:
240
241 Install the package at `https://github.com/githubname/githubrepo` by attempting to clone it using `git`.
242
243 If `#<commit-ish>` is provided, it will be used to clone exactly that commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is specified, then the default branch is used.
244
245 As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
246
247 Examples:
248
249 ```bash
250 npm install mygithubuser/myproject
251 npm install github:mygithubuser/myproject
252 ```
253
254 - `npm install gist:[<githubname>/]<gistID>[#<commit-ish>|#semver:<semver>]`:
255
256 Install the package at `https://gist.github.com/gistID` by attempting to clone it using `git`. The GitHub username associated with the gist is optional and will not be saved in `package.json`.
257
258 As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
259
260 Example:
261
262 ```bash
263 npm install gist:101a11beef
264 ```
265
266 - `npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]`:
267
268 Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo` by attempting to clone it using `git`.
269
270 If `#<commit-ish>` is provided, it will be used to clone exactly that commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is specified, then `master` is used.
271
272 As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
273
274 Example:
275
276 ```bash
277 npm install bitbucket:mybitbucketuser/myproject
278 ```
279
280 - `npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]`:
281
282 Install the package at `https://gitlab.com/gitlabname/gitlabrepo` by attempting to clone it using `git`.
283
284 If `#<commit-ish>` is provided, it will be used to clone exactly that commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is specified, then `master` is used.
285
286 As with regular git dependencies, `dependencies` and `devDependencies` will be installed if the package has a `prepare` script before the package is done installing.
287
288 Example:
289
290 ```bash
291 npm install gitlab:mygitlabuser/myproject
292 npm install gitlab:myusr/myproj#semver:^5.0
293 ```
294
295 You may combine multiple arguments and even multiple types of arguments. For example:
296
297 ```bash
298 npm install sax@">=0.1.0 <0.2.0" bench supervisor
299 ```
300
301 The `--tag` argument will apply to all of the specified install targets. If a tag with the given name exists, the tagged version is preferred over newer versions.
302
303 The `--dry-run` argument will report in the usual way what the install would have done without actually installing anything.
304
305 The `--package-lock-only` argument will only update the `package-lock.json`, instead of checking `node_modules` and downloading dependencies.
306
307 The `-f` or `--force` argument will force npm to fetch remote resources even if a local copy exists on disk.
308
309 ```bash
310 npm install sax --force
311 ```
312
313 ### Configuration
314
315 See the [`config`](/cli/v10/using-npm/config) help doc. Many of the configuration params have some effect on installation, since that's most of what npm does.
316
317 These are some of the most common options related to installation.
318
319 #### `save`
320
321 - Default: `true` unless when using `npm update` where it defaults to `false`
322 - Type: Boolean
323
324 Save installed packages to a `package.json` file as dependencies.
325
326 When used with the `npm rm` command, removes the dependency from `package.json`.
327
328 Will also prevent writing to `package-lock.json` if set to `false`.
329
330 #### `save-exact`
331
332 - Default: false
333 - Type: Boolean
334
335 Dependencies saved to package.json will be configured with an exact version rather than using npm's default semver range operator.
336
337 #### `global`
338
339 - Default: false
340 - Type: Boolean
341
342 Operates in "global" mode, so that packages are installed into the `prefix` folder instead of the current working directory. See [folders](/cli/v10/configuring-npm/folders) for more on the differences in behavior.
343
344 - packages are installed into the `{prefix}/lib/node_modules` folder, instead of the current working directory.
345 - bin files are linked to `{prefix}/bin`
346 - man pages are linked to `{prefix}/share/man`
347
348 #### `install-strategy`
349
350 - Default: "hoisted"
351 - Type: "hoisted", "nested", "shallow", or "linked"
352
353 Sets the strategy for installing packages in node_modules. hoisted (default): Install non-duplicated in top-level, and duplicated as necessary within directory structure. nested: (formerly --legacy-bundling) install in place, no hoisting. shallow (formerly --global-style) only install direct deps at top-level. linked: (experimental) install in node_modules/.store, link in place, unhoisted.
354
355 #### `legacy-bundling`
356
357 - Default: false
358 - Type: Boolean
359 - DEPRECATED: This option has been deprecated in favor of `--install-strategy=nested`
360
361 Instead of hoisting package installs in `node_modules`, install packages in the same manner that they are depended on. This may cause very deep directory structures and duplicate package installs as there is no de-duplicating. Sets `--install-strategy=nested`.
362
363 #### `global-style`
364
365 - Default: false
366 - Type: Boolean
367 - DEPRECATED: This option has been deprecated in favor of `--install-strategy=shallow`
368
369 Only install direct dependencies in the top level `node_modules`, but hoist on deeper dependencies. Sets `--install-strategy=shallow`.
370
371 #### `omit`
372
373 - Default: 'dev' if the `NODE_ENV` environment variable is set to 'production', otherwise empty.
374 - Type: "dev", "optional", or "peer" (can be set multiple times)
375
376 Dependency types to omit from the installation tree on disk.
377
378 Note that these dependencies _are_ still resolved and added to the `package-lock.json` or `npm-shrinkwrap.json` file. They are just not physically installed on disk.
379
380 If a package type appears in both the `--include` and `--omit` lists, then it will be included.
381
382 If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment variable will be set to `'production'` for all lifecycle scripts.
383
384 #### `include`
385
386 - Default:
387 - Type: "prod", "dev", "optional", or "peer" (can be set multiple times)
388
389 Option that allows for defining which types of dependencies to install.
390
391 This is the inverse of `--omit=<type>`.
392
393 Dependency types specified in `--include` will not be omitted, regardless of the order in which omit/include are specified on the command-line.
394
395 #### `strict-peer-deps`
396
397 - Default: false
398 - Type: Boolean
399
400 If set to `true`, and `--legacy-peer-deps` is not set, then _any_ conflicting `peerDependencies` will be treated as an install failure, even if npm could reasonably guess the appropriate resolution based on non-peer dependency relationships.
401
402 By default, conflicting `peerDependencies` deep in the dependency graph will be resolved using the nearest non-peer dependency specification, even if doing so will result in some packages receiving a peer dependency outside the range set in their package's `peerDependencies` object.
403
404 When such an override is performed, a warning is printed, explaining the conflict and the packages involved. If `--strict-peer-deps` is set, then this warning is treated as a failure.
405
406 #### `prefer-dedupe`
407
408 - Default: false
409 - Type: Boolean
410
411 Prefer to deduplicate packages if possible, rather than choosing a newer version of a dependency.
412
413 #### `package-lock`
414
415 - Default: true
416 - Type: Boolean
417
418 If set to false, then ignore `package-lock.json` files when installing. This will also prevent _writing_ `package-lock.json` if `save` is true.
419
420 #### `package-lock-only`
421
422 - Default: false
423 - Type: Boolean
424
425 If set to true, the current operation will only use the `package-lock.json`, ignoring `node_modules`.
426
427 For `update` this means only the `package-lock.json` will be updated, instead of checking `node_modules` and downloading dependencies.
428
429 For `list` this means the output will be based on the tree described by the `package-lock.json`, rather than the contents of `node_modules`.
430
431 #### `foreground-scripts`
432
433 - Default: `false` unless when using `npm pack` or `npm publish` where it defaults to `true`
434 - Type: Boolean
435
436 Run all build scripts (ie, `preinstall`, `install`, and `postinstall`) scripts for installed packages in the foreground process, sharing standard input, output, and error with the main npm process.
437
438 Note that this will generally make installs run slower, and be much noisier, but can be useful for debugging.
439
440 #### `ignore-scripts`
441
442 - Default: false
443 - Type: Boolean
444
445 If true, npm does not run scripts specified in package.json files.
446
447 Note that commands explicitly intended to run a particular script, such as `npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script` will still run their intended script if `ignore-scripts` is set, but they will _not_ run any pre- or post-scripts.
448
449 #### `audit`
450
451 - Default: true
452 - Type: Boolean
453
454 When "true" submit audit reports alongside the current npm command to the default registry and all registries configured for scopes. See the documentation for [`npm audit`](/cli/v10/commands/npm-audit) for details on what is submitted.
455
456 #### `bin-links`
457
458 - Default: true
459 - Type: Boolean
460
461 Tells npm to create symlinks (or `.cmd` shims on Windows) for package executables.
462
463 Set to false to have it not do this. This can be used to work around the fact that some file systems don't support symlinks, even on ostensibly Unix systems.
464
465 #### `fund`
466
467 - Default: true
468 - Type: Boolean
469
470 When "true" displays the message at the end of each `npm install` acknowledging the number of dependencies looking for funding. See [`npm fund`](/cli/v10/commands/npm-fund) for details.
471
472 #### `dry-run`
473
474 - Default: false
475 - Type: Boolean
476
477 Indicates that you don't want npm to make any changes and that it should only report what it would have done. This can be passed into any of the commands that modify your local installation, eg, `install`, `update`, `dedupe`, `uninstall`, as well as `pack` and `publish`.
478
479 Note: This is NOT honored by other network related commands, eg `dist-tags`, `owner`, etc.
480
481 #### `cpu`
482
483 - Default: null
484 - Type: null or String
485
486 Override CPU architecture of native modules to install. Acceptable values are same as `cpu` field of package.json, which comes from `process.arch`.
487
488 #### `os`
489
490 - Default: null
491 - Type: null or String
492
493 Override OS of native modules to install. Acceptable values are same as `os` field of package.json, which comes from `process.platform`.
494
495 #### `libc`
496
497 - Default: null
498 - Type: null or String
499
500 Override libc of native modules to install. Acceptable values are same as `libc` field of package.json
501
502 #### `workspace`
503
504 - Default:
505 - Type: String (can be set multiple times)
506
507 Enable running a command in the context of the configured workspaces of the current project while filtering by running only the workspaces defined by this configuration option.
508
509 Valid values for the `workspace` config are either:
510
511 - Workspace names
512 - Path to a workspace directory
513 - Path to a parent workspace directory (will result in selecting all workspaces within that folder)
514
515 When set for the `npm init` command, this may be set to the folder of a workspace which does not yet exist, to create the folder and set it up as a brand new workspace within the project.
516
517 This value is not exported to the environment for child processes.
518
519 #### `workspaces`
520
521 - Default: null
522 - Type: null or Boolean
523
524 Set to true to run the command in the context of **all** configured workspaces.
525
526 Explicitly setting this to false will cause commands like `install` to ignore workspaces altogether. When not set explicitly:
527
528 - Commands that operate on the `node_modules` tree (install, update, etc.) will link workspaces into the `node_modules` folder. - Commands that do other things (test, exec, publish, etc.) will operate on the root project, _unless_ one or more workspaces are specified in the `workspace` config.
529
530 This value is not exported to the environment for child processes.
531
532 #### `include-workspace-root`
533
534 - Default: false
535 - Type: Boolean
536
537 Include the workspace root when workspaces are enabled for a command.
538
539 When false, specifying individual workspaces via the `workspace` config, or all workspaces via the `workspaces` flag, will cause npm to operate only on the specified workspaces, and not on the root project.
540
541 This value is not exported to the environment for child processes.
542
543 #### `install-links`
544
545 - Default: false
546 - Type: Boolean
547
548 When set file: protocol dependencies will be packed and installed as regular dependencies instead of creating a symlink. This option has no effect on workspaces.
549
550 ### Algorithm
551
552 Given a `package{dep}` structure: `A{B,C}, B{C}, C{D}`, the npm install algorithm produces:
553
554 ```bash
555 A
556 +-- B
557 +-- C
558 +-- D
559 ```
560
561 That is, the dependency from B to C is satisfied by the fact that A already caused C to be installed at a higher level. D is still installed at the top level because nothing conflicts with it.
562
563 For `A{B,C}, B{C,D@1}, C{D@2}`, this algorithm produces:
564
565 ```bash
566 A
567 +-- B
568 +-- C
569 `-- D@2
570 +-- D@1
571 ```
572
573 Because B's D@1 will be installed in the top-level, C now has to install D@2 privately for itself. This algorithm is deterministic, but different trees may be produced if two dependencies are requested for installation in a different order.
574
575 See [folders](/cli/v10/configuring-npm/folders) for a more detailed description of the specific folder structures that npm creates.
576
577 ### See Also
578
579 - [npm folders](/cli/v10/configuring-npm/folders)
580 - [npm update](/cli/v10/commands/npm-update)
581 - [npm audit](/cli/v10/commands/npm-audit)
582 - [npm fund](/cli/v10/commands/npm-fund)
583 - [npm link](/cli/v10/commands/npm-link)
584 - [npm rebuild](/cli/v10/commands/npm-rebuild)
585 - [npm scripts](/cli/v10/using-npm/scripts)
586 - [npm config](/cli/v10/commands/npm-config)
587 - [npmrc](/cli/v10/configuring-npm/npmrc)
588 - [npm registry](/cli/v10/using-npm/registry)
589 - [npm dist-tag](/cli/v10/commands/npm-dist-tag)
590 - [npm uninstall](/cli/v10/commands/npm-uninstall)
591 - [npm shrinkwrap](/cli/v10/commands/npm-shrinkwrap)
592 - [package.json](/cli/v10/configuring-npm/package-json)
593 - [workspaces](/cli/v10/using-npm/workspaces)