1NPM-INSTALL(1)                                                  NPM-INSTALL(1)
2
3
4

NAME

6       npm-install - Install a package
7
8   Synopsis
9         npm install (with no args, in package dir)
10         npm install [<@scope>/]<name>
11         npm install [<@scope>/]<name>@<tag>
12         npm install [<@scope>/]<name>@<version>
13         npm install [<@scope>/]<name>@<version range>
14         npm install <alias>@npm:<name>
15         npm install <git-host>:<git-user>/<repo-name>
16         npm install <git repo url>
17         npm install <tarball file>
18         npm install <tarball url>
19         npm install <folder>
20
21         aliases: npm i, npm add
22         common options: [-P|--save-prod|-D|--save-dev|-O|--save-optional] [-E|--save-exact] [-B|--save-bundle] [--no-save] [--dry-run]
23
24   Description
25       This  command  installs a package, and any packages that it depends on.
26       If the package has a package-lock or shrinkwrap file, the  installation
27       of  dependencies  will  be  driven by that, with an npm-shrinkwrap.json
28       taking precedence if both files exist. See npm  help  package-lock.json
29       and npm help shrinkwrap.
30
31       A package is:
32
33       · a) a folder containing a program described by a npm help package.json
34         file
35
36       · b) a gzipped tarball containing (a)
37
38       · c) a url that resolves to (b)
39
40       · d) a <name>@<version> that is published on the registry (see npm help
41         registry) with (c)
42
43       · e) a <name>@<tag> (see npm help dist-tag) that points to (d)
44
45       · f) a <name> that has a "latest" tag satisfying (e)
46
47       · g) a <git remote url> that resolves to (a)
48
49
50       Even if you never publish your package, you can still get a lot of ben‐
51       efits of using npm if you just want to write a node  program  (a),  and
52       perhaps  if  you  also  want  to be able to easily install it elsewhere
53       after packing it up into a tarball (b).
54
55       · npm install (in package directory, no arguments):
56           Install the dependencies in the local node_modules folder.
57           In global mode (ie, with -g or --global appended to the command),
58           it installs the current package context (ie, the current working
59           directory) as a global package.
60           By default, npm install will install all modules listed  as  depen‐
61         dencies
62           in npm help package.json.
63           With  the --production flag (or when the NODE_ENV environment vari‐
64         able
65           is set to production), npm will not install modules listed in
66           devDependencies. To install all modules listed in both dependencies
67           and devDependencies when NODE_ENV environment variable  is  set  to
68         production,
69           you can use --production=false.  NOTE: The --production flag has no
70         particular meaning when adding a
71           dependency to a project.
72
73
74       · npm install <folder>:
75           Install the package in the directory as a symlink  in  the  current
76         project.
77           Its  dependencies will be installed before it's linked. If <folder>
78         sits
79           inside the root of your project, its dependencies may be hoisted to
80         the
81           toplevel  node_modules  as  they would for other types of dependen‐
82         cies.
83
84       · npm install <tarball file>:
85           Install a package that is sitting on the filesystem.  Note: if  you
86         just want
87           to  link  a  dev directory into your npm root, you can do this more
88         easily by
89           using npm link.
90           Tarball requirements:
91
92         · The filename must use .tar, .tar.gz, or .tgz as the extension.
93
94         · The package contents should reside in a subfolder inside  the  tar‐
95           ball  (usually  it  is  called  package/). npm strips one directory
96           layer  when  installing  the  package  (an  equivalent  of  tar   x
97           --strip-components=1 is run).
98
99         · The  package must contain a package.json file with name and version
100           properties.  Example:
101
102           npm install ./package.tgz
103
104
105       · npm install <tarball url>:
106           Fetch the tarball url, and then install it.  In  order  to  distin‐
107         guish between
108           this  and  other options, the argument must start with "http://" or
109         "https://"
110           Example:
111
112             npm install https://github.com/indexzero/forever/tarball/v0.5.6
113
114       · npm install [<@scope>/]<name>:
115           Do a <name>@<tag> install, where <tag> is the "tag" config. (See
116           npm help config. The config's default value is latest.)
117           In most cases, this will install the version of the modules  tagged
118         as
119           latest on the npm registry.
120           Example:
121
122             npm install sax
123
124       · npm install <alias>@npm:<name>:
125           Install a package under a custom alias. Allows multiple versions of
126           a same-name package side-by-side, more convenient import names for
127           packages with otherwise long ones and using git forks replacements
128           or forked npm packages as replacements. Aliasing works only on your
129           project and does not rename packages in transitive dependencies.
130           Aliases should follow the naming conventions stated in
131           validate-npm-package-name       https://www.npmjs.com/package/vali
132         date-npm-package-name#naming-rules.
133           Examples:
134
135             npm install my-react@npm:react
136             npm install jquery2@npm:jquery@2
137             npm install jquery3@npm:jquery@3
138             npm install npa@npm:npm-package-arg
139
140
141         `npm install` saves any specified packages into `dependencies` by default.
142         Additionally, you can control where and how they get saved with some
143         additional flags:
144
145         * `-P, --save-prod`: Package will appear in your `dependencies`. This is the
146                              default unless `-D` or `-O` are present.
147
148         * `-D, --save-dev`: Package will appear in your `devDependencies`.
149
150         * `-O, --save-optional`: Package will appear in your `optionalDependencies`.
151
152         * `--no-save`: Prevents saving to `dependencies`.
153
154         When using any of the above options to save dependencies to your
155         package.json, there are two additional, optional flags:
156
157         * `-E, --save-exact`: Saved dependencies will be configured with an
158           exact version rather than using npm's default semver range
159           operator.
160
161         * `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list.
162
163         Further, if you have an `npm-shrinkwrap.json` or `package-lock.json` then it
164         will be updated as well.
165
166         `<scope>` is optional. The package will be downloaded from the registry
167         associated with the specified scope. If no registry is associated with
168         the given scope the default registry is assumed. See npm help `scope`.
169
170         Note: if you do not include the @-symbol on your scope name, npm will
171         interpret this as a GitHub repository instead, see below. Scopes names
172         must also be followed by a slash.
173
174         Examples:
175
176         ```bash
177         npm install sax
178         npm install githubname/reponame
179         npm install @myorg/privatepackage
180         npm install node-tap --save-dev
181         npm install dtrace-provider --save-optional
182         npm install readable-stream --save-exact
183         npm install ansi-regex --save-bundle
184         ```
185
186         **Note**: If there is a file or folder named `<name>` in the current
187         working directory, then it will try to install that, and only try to
188         fetch the package by name if it is not valid.
189
190       · npm install [<@scope>/]<name>@<tag>:
191           Install the version of the package that is referenced by the speci‐
192         fied tag.
193           If  the  tag  does not exist in the registry data for that package,
194         then this
195           will fail.
196           Example:
197
198           npm install sax@latest
199           npm install @myorg/mypackage@latest
200
201       · npm install [<@scope>/]<name>@<version>:
202           Install the specified version of the package.  This  will  fail  if
203         the
204           version has not been published to the registry.
205           Example:
206
207           npm install sax@0.1.1
208           npm install @myorg/privatepackage@1.5.0
209
210       · npm install [<@scope>/]<name>@<version range>:
211           Install  a  version  of  the package matching the specified version
212         range.  This
213           will follow the same rules for resolving dependencies described  in
214         npm help package.json.
215           Note  that  most  version ranges must be put in quotes so that your
216         shell will
217           treat it as a single argument.
218           Example:
219
220           npm install sax@">=0.1.0 <0.2.0"
221           npm install @myorg/privatepackage@">=0.1.0 <0.2.0"
222
223       · npm install <git remote url>:
224           Installs the package from the hosted git provider, cloning it  with
225         git.
226           For a full git remote url, only that URL will be attempted.
227
228             <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
229         <protocol> is one of git, git+ssh, git+http, git+https, or
230         git+file.
231         If #<commit-ish> is provided, it will be used to clone exactly that
232         commit.  If  the commit-ish has the format #semver:<semver>, <semver>
233       can
234         be any valid semver range or exact version, and npm will look for any
235       tags
236         or  refs  matching  that  range  in the remote repository, much as it
237       would for a
238         registry dependency. If neither #<commit-ish> or #semver:<semver> is
239         specified, then the default branch of the repository is used.
240         If the repository makes use of submodules, those submodules  will  be
241       cloned
242         as well.
243         If the package being installed contains a prepare script, its
244         dependencies and devDependencies will be installed, and the prepare
245         script will be run, before the package is packaged and installed.
246         The  following  git  environment  variables are recognized by npm and
247       will be
248         added to the environment when running git:
249
250              · GIT_ASKPASS
251
252              · GIT_EXEC_PATH
253
254              · GIT_PROXY_COMMAND
255
256              · GIT_SSH
257
258              · GIT_SSH_COMMAND
259
260              · GIT_SSL_CAINFO
261
262              · GIT_SSL_NO_VERIFY See the git man page for details.  Examples:
263
264                npm install git+ssh://git@github.com:npm/cli.git#v1.0.27
265                npm install git+ssh://git@github.com:npm/cli#semver:^5.0
266                npm install git+https://isaacs@github.com/npm/cli.git
267                npm install git://github.com/npm/cli.git#v1.0.27
268                GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git
269
270
271       · npm install <githubname>/<githubrepo>[#<commit-ish>]:
272
273       · npm install github:<githubname>/<githubrepo>[#<commit-ish>]:
274           Install the package at https://github.com/githubname/githubrepo by
275           attempting to clone it using git.
276           If #<commit-ish> is provided, it will be used to clone exactly that
277           commit. If the commit-ish has the format #semver:<semver>, <semver>
278         can
279           be  any  valid semver range or exact version, and npm will look for
280         any tags
281           or refs matching that range in the remote repository,  much  as  it
282         would for a
283           registry  dependency.  If neither #<commit-ish> or #semver:<semver>
284         is
285           specified, then master is used.
286           As with regular git dependencies, dependencies and  devDependencies
287         will
288           be  installed if the package has a prepare script, before the pack‐
289         age is
290           done installing.
291           Examples:
292
293           npm install mygithubuser/myproject
294           npm install github:mygithubuser/myproject
295
296       · npm            install            gist:[<githubname>/]<gistID>[#<com‐
297         mit-ish>|#semver:<semver>]:
298           Install the package at https://gist.github.com/gistID by attempting
299         to
300           clone it using git. The GitHub username associated with the gist is
301           optional and will not be saved in package.json.
302           As with regular git dependencies, dependencies and  devDependencies
303         will
304           be  installed if the package has a prepare script, before the pack‐
305         age is
306           done installing.
307           Example:
308
309           npm install gist:101a11beef
310
311       · npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]:
312           Install the package at https://bitbucket.org/bitbucketname/bitbuck
313         etrepo
314           by attempting to clone it using git.
315           If #<commit-ish> is provided, it will be used to clone exactly that
316           commit. If the commit-ish has the format #semver:<semver>, <semver>
317         can
318           be any valid semver range or exact version, and npm will  look  for
319         any tags
320           or  refs  matching  that range in the remote repository, much as it
321         would for a
322           registry dependency. If neither #<commit-ish>  or  #semver:<semver>
323         is
324           specified, then master is used.
325           As  with regular git dependencies, dependencies and devDependencies
326         will
327           be installed if the package has a prepare script, before the  pack‐
328         age is
329           done installing.
330           Example:
331
332           npm install bitbucket:mybitbucketuser/myproject
333
334       · npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]:
335           Install the package at https://gitlab.com/gitlabname/gitlabrepo
336           by attempting to clone it using git.
337           If #<commit-ish> is provided, it will be used to clone exactly that
338           commit. If the commit-ish has the format #semver:<semver>, <semver>
339         can
340           be any valid semver range or exact version, and npm will  look  for
341         any tags
342           or  refs  matching  that range in the remote repository, much as it
343         would for a
344           registry dependency. If neither #<commit-ish>  or  #semver:<semver>
345         is
346           specified, then master is used.
347           As  with regular git dependencies, dependencies and devDependencies
348         will
349           be installed if the package has a prepare script, before the  pack‐
350         age is
351           done installing.
352           Example:
353
354           npm install gitlab:mygitlabuser/myproject
355           npm install gitlab:myusr/myproj#semver:^5.0
356
357
358       You  may  combine  multiple arguments, and even multiple types of argu‐
359       ments.  For example:
360
361         npm install sax@">=0.1.0 <0.2.0" bench supervisor
362
363       The --tag argument will apply to all of the specified install  targets.
364       If  a  tag  with the given name exists, the tagged version is preferred
365       over newer versions.
366
367       The --dry-run argument will report in the usual way  what  the  install
368       would have done without actually installing anything.
369
370       The   --package-lock-only   argument   will   only   update  the  pack‐
371       age-lock.json, instead of checking node_modules and downloading  depen‐
372       dencies.
373
374       The  -f  or  --force  argument will force npm to fetch remote resources
375       even if a local copy exists on disk.
376
377         npm install sax --force
378
379       The --no-fund argument will hide the message displayed at  the  end  of
380       each  install  that acknowledges the number of dependencies looking for
381       funding.  See npm-fund(1)
382
383       The -g or --global argument will cause npm to install the package glob‐
384       ally rather than locally.  See npm help folders.
385
386       The  --global-style argument will cause npm to install the package into
387       your local node_modules folder with the same layout it  uses  with  the
388       global  node_modules folder. Only your direct dependencies will show in
389       node_modules and everything they depend on will be flattened  in  their
390       node_modules folders. This obviously will eliminate some deduping.
391
392       The --ignore-scripts argument will cause npm to not execute any scripts
393       defined in the package.json. See npm help scripts.
394
395       The --legacy-bundling argument will cause npm to  install  the  package
396       such  that  versions of npm prior to 1.4, such as the one included with
397       node 0.8, can install the package. This eliminates all automatic dedup‐
398       ing.
399
400       The  --link  argument  will  cause npm to link global installs into the
401       local space in some cases.
402
403       The --no-bin-links argument will prevent npm from creating symlinks for
404       any binaries the package might contain.
405
406       The  --no-optional  argument  will  prevent  optional dependencies from
407       being installed.
408
409       The --no-shrinkwrap argument, which will ignore  an  available  package
410       lock or shrinkwrap file and use the package.json instead.
411
412       The  --no-package-lock  argument will prevent npm from creating a pack‐
413       age-lock.json file.  When running with package-lock's disabled npm will
414       not automatically prune your node modules when installing.
415
416       The  --nodedir=/path/to/node/source argument will allow npm to find the
417       node source code so that npm can compile native modules.
418
419       The --only={prod[uction]|dev[elopment]} argument will cause either only
420       devDependencies  or only non-devDependencies to be installed regardless
421       of the NODE_ENV.
422
423       The --no-audit argument can be used to disable sending of audit reports
424       to  the  configured registries.  See npm-audit npm-audit for details on
425       what is sent.
426
427       See npm help config.  Many of the configuration params have some effect
428       on installation, since that's most of what npm does.
429
430   Algorithm
431       To install a package, npm uses the following algorithm:
432
433         load the existing node_modules tree from disk
434         clone the tree
435         fetch the package.json and assorted metadata and add it to the clone
436         walk the clone and add any missing dependencies
437           dependencies will be added as close to the top as is possible
438           without breaking any other modules
439         compare the original tree with the cloned tree and make a list of
440         actions to take to convert one to the other
441         execute all of the actions, deepest first
442           kinds of actions are install, update, remove and move
443
444       For  this  package{dep}  structure:  A{B,C}, B{C}, C{D}, this algorithm
445       produces:
446
447         A
448         +-- B
449         +-- C
450         +-- D
451
452       That is, the dependency from B to C is satisfied by  the  fact  that  A
453       already  caused  C  to  be  installed  at  a  higher  level. D is still
454       installed at the top level because nothing conflicts with it.
455
456       For A{B,C}, B{C,D@1}, C{D@2}, this algorithm produces:
457
458         A
459         +-- B
460         +-- C
461            `-- D@2
462         +-- D@1
463
464       Because B's D@1 will be installed in  the  top  level,  C  now  has  to
465       install  D@2 privately for itself. This algorithm is deterministic, but
466       different trees may be produced if two dependencies are  requested  for
467       installation in a different order.
468
469       See  npm  help  folders for a more detailed description of the specific
470       folder structures that npm creates.
471
472   Limitations of npm's Install Algorithm
473       npm will refuse to install any package with an identical  name  to  the
474       current  package.  This can be overridden with the --force flag, but in
475       most cases can simply be addressed by changing the local package name.
476
477       There are some very rare and pathological edge-cases where a cycle  can
478       cause  npm  to try to install a never-ending tree of packages.  Here is
479       the simplest case:
480
481         A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...
482
483       where A is some version of a package, and A' is a different version  of
484       the  same  package.  Because B depends on a different version of A than
485       the one that is already in the tree, it must install a  separate  copy.
486       The  same  is true of A', which must install B'.  Because B' depends on
487       the original version of A, which has been overridden, the  cycle  falls
488       into infinite regress.
489
490       To  avoid this situation, npm flat-out refuses to install any name@ver‐
491       sion that is already present anywhere in the  tree  of  package  folder
492       ancestors.  A more correct, but more complex, solution would be to sym‐
493       link the existing version into the new location.  If this ever  affects
494       a real use-case, it will be investigated.
495
496   See Also
497       · npm help folders
498
499       · npm help update
500
501       · npm help audit
502
503       · npm help fund
504
505       · npm help link
506
507       · npm help rebuild
508
509       · npm help scripts
510
511       · npm help build
512
513       · npm help config
514
515       · npm help npmrc
516
517       · npm help registry
518
519       · npm help dist-tag
520
521       · npm help uninstall
522
523       · npm help shrinkwrap
524
525       · npm help package.json
526
527
528
529
530                                  March 2020                    NPM-INSTALL(1)
Impressum