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|--save-peer] [-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. If
26       the package has a package-lock, or an npm shrinkwrap file,  or  a  yarn
27       lock file, the installation of dependencies will be driven by that, re‐
28       specting the following order of precedence:
29
30       • npm-shrinkwrap.json
31
32       • package-lock.json
33
34       • yarn.lock
35
36
37       See npm help package-lock.json and npm help shrinkwrap.
38
39       A package is:
40
41       • a) a folder containing a program described by a npm help package.json
42         file
43
44       • b) a gzipped tarball containing (a)
45
46       • c) a url that resolves to (b)
47
48       • d) a <name>@<version> that is published on the registry (see npm help
49         registry) with (c)
50
51       • e) a <name>@<tag> (see npm help dist-tag) that points to (d)
52
53       • f) a <name> that has a "latest" tag satisfying (e)
54
55       • g) a <git remote url> that resolves to (a)
56
57
58       Even if you never publish your package, you can still get a lot of ben‐
59       efits  of  using  npm if you just want to write a node program (a), and
60       perhaps if you also want to be able to easily install it elsewhere  af‐
61       ter packing it up into a tarball (b).
62
63       • npm install (in a package directory, no arguments):
64           Install the dependencies to the local node_modules folder.
65           In global mode (ie, with -g or --global appended to the command),
66           it installs the current package context (ie, the current working
67           directory) as a global package.
68           By default, npm install will install all modules listed as
69           dependencies in npm help package.json.
70           With the --production flag (or when the NODE_ENV environment
71           variable is set to production), npm will not install modules listed
72           in devDependencies. To install all modules listed in both
73           dependencies and devDependencies when NODE_ENV environment
74           variable  is  set  to  production,  you can use --production=false.
75         NOTE: The --production flag has no particular meaning when adding a
76           dependency to a project.
77
78
79       • npm install <folder>:
80           Install the package in the directory as a symlink in the current
81           project.  Its dependencies will be installed before it's linked. If
82           <folder> sits inside the root of your project, its dependencies may
83           be hoisted to the top-level node_modules as they would for other
84           types of dependencies.
85
86       • npm install <tarball file>:
87           Install a package that is sitting on the filesystem.  Note: if  you
88         just
89           want  to  link  a dev directory into your npm root, you can do this
90         more
91           easily by using npm help link.
92           Tarball requirements:
93
94         • The filename must use .tar, .tar.gz, or .tgz as the extension.
95
96         • The package contents should reside in a subfolder inside  the  tar‐
97           ball  (usually  it  is  called  package/). npm strips one directory
98           layer  when  installing  the  package  (an  equivalent  of  tar   x
99           --strip-components=1 is run).
100
101         • The  package must contain a package.json file with name and version
102           properties.  Example:
103
104           npm install ./package.tgz
105
106
107       • npm install <tarball url>:
108           Fetch the tarball url, and then install it.  In  order  to  distin‐
109         guish between
110           this  and  other options, the argument must start with "http://" or
111         "https://"
112           Example:
113
114           npm install https://github.com/indexzero/forever/tarball/v0.5.6
115
116       • npm install [<@scope>/]<name>:
117           Do a <name>@<tag> install, where <tag> is the "tag" config. (See
118           npm help config. The config's default value is latest.)
119           In most cases, this will install the version of the modules  tagged
120         as
121           latest on the npm registry.
122           Example:
123
124           npm install sax
125         npm  install  saves  any  specified packages into dependencies by de‐
126       fault.
127         Additionally, you can control where and how they get saved with some
128         additional flags:
129
130              • -P, --save-prod: Package will  appear  in  your  dependencies.
131                This is the default unless -D or -O are present.
132
133              • -D, --save-dev: Package will appear in your devDependencies.
134
135              • -O,  --save-optional:  Package will appear in your optionalDe‐
136                pendencies.
137
138              • --no-save: Prevents saving to dependencies.  When using any of
139                the  above  options to save dependencies to your package.json,
140                there are two additional, optional flags:
141
142              • -E, --save-exact: Saved dependencies will be  configured  with
143                an  exact version rather than using npm's default semver range
144                operator.
145
146              • -B, --save-bundle: Saved dependencies will also  be  added  to
147                your   bundleDependencies  list.   Further,  if  you  have  an
148                npm-shrinkwrap.json or package-lock.json then it will  be  up‐
149                dated as well.  <scope> is optional. The package will be down‐
150                loaded from the registry associated with the specified  scope.
151                If  no registry is associated with the given scope the default
152                registry is assumed. See npm help scope.  Note: if you do  not
153                include  the  @-symbol  on your scope name, npm will interpret
154                this as a GitHub repository instead, see below.  Scopes  names
155                must also be followed by a slash.  Examples:
156
157                npm install sax
158                npm install githubname/reponame
159                npm install @myorg/privatepackage
160                npm install node-tap --save-dev
161                npm install dtrace-provider --save-optional
162                npm install readable-stream --save-exact
163                npm install ansi-regex --save-bundle
164
165              • Note*:  If  there is a file or folder named <name> in the cur‐
166                rent working directory, then it will try to install that,  and
167                only try to fetch the package by name if it is not valid.
168
169
170       • npm install <alias>@npm:<name>:
171           Install a package under a custom alias. Allows multiple versions of
172           a same-name package side-by-side, more convenient import names for
173           packages with otherwise long ones, and using git forks replacements
174           or forked npm packages as replacements. Aliasing works only on your
175           project and does not rename packages in transitive dependencies.
176           Aliases should follow the naming conventions stated in
177           validate-npm-package-name       https://www.npmjs.com/package/vali‐
178         date-npm-package-name#naming-rules.
179           Examples:
180
181           npm install my-react@npm:react
182           npm install jquery2@npm:jquery@2
183           npm install jquery3@npm:jquery@3
184           npm install npa@npm:npm-package-arg
185
186       • npm install [<@scope>/]<name>@<tag>:
187           Install the version of the package that is referenced by the speci‐
188         fied tag.
189           If  the  tag  does not exist in the registry data for that package,
190         then this
191           will fail.
192           Example:
193
194           npm install sax@latest
195           npm install @myorg/mypackage@latest
196
197       • npm install [<@scope>/]<name>@<version>:
198           Install the specified version of the package.  This  will  fail  if
199         the
200           version has not been published to the registry.
201           Example:
202
203           npm install sax@0.1.1
204           npm install @myorg/privatepackage@1.5.0
205
206       • npm install [<@scope>/]<name>@<version range>:
207           Install  a  version  of  the package matching the specified version
208         range.
209           This will follow the same  rules  for  resolving  dependencies  de‐
210         scribed in
211           npm help package.json.
212           Note  that  most  version ranges must be put in quotes so that your
213         shell
214           will treat it as a single argument.
215           Example:
216
217           npm install sax@">=0.1.0 <0.2.0"
218           npm install @myorg/privatepackage@"16 - 17"
219
220       • npm install <git remote url>:
221           Installs the package from the hosted git provider, cloning it with
222           git.  For a full git remote url, only that URL will be attempted.
223
224           <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
225         <protocol> is one of git, git+ssh, git+http, git+https, or
226         git+file.
227         If #<commit-ish> is provided, it will be used to clone exactly that
228         commit. If the commit-ish has the format #semver:<semver>, <semver>
229         can be any valid semver range or exact version, and npm will look for
230         any tags or refs matching that range in the remote  repository,  much
231       as
232         it would for a registry dependency. If neither #<commit-ish> or
233         #semver:<semver> is specified, then the default branch of the
234         repository is used.
235         If the repository makes use of submodules, those submodules will be
236         cloned as well.
237         If the package being installed contains a prepare script, its
238         dependencies and devDependencies will be installed, and the prepare
239         script will be run, before the package is packaged and installed.
240         The  following  git  environment  variables are recognized by npm and
241       will
242         be added to the environment when running git:
243
244              • GIT_ASKPASS
245
246              • GIT_EXEC_PATH
247
248              • GIT_PROXY_COMMAND
249
250              • GIT_SSH
251
252              • GIT_SSH_COMMAND
253
254              • GIT_SSL_CAINFO
255
256              • GIT_SSL_NO_VERIFY See the git man page for details.  Examples:
257
258                npm install git+ssh://git@github.com:npm/cli.git#v1.0.27
259                npm install git+ssh://git@github.com:npm/cli#pull/273
260                npm install git+ssh://git@github.com:npm/cli#semver:^5.0
261                npm install git+https://isaacs@github.com/npm/cli.git
262                npm install git://github.com/npm/cli.git#v1.0.27
263                GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git
264
265
266       • npm install <githubname>/<githubrepo>[#<commit-ish>]:
267
268       • npm install github:<githubname>/<githubrepo>[#<commit-ish>]:
269           Install the package at https://github.com/githubname/githubrepo by
270           attempting to clone it using git.
271           If #<commit-ish> is provided, it will be used to clone exactly that
272           commit. If the commit-ish has the format #semver:<semver>, <semver>
273           can be any valid semver range or exact version, and npm  will  look
274         for
275           any tags or refs matching that range in the remote repository, much
276         as
277           it would for a registry dependency. If neither #<commit-ish> or
278           #semver:<semver> is specified, then master is used.
279           As with regular git dependencies, dependencies and devDependencies
280           will be installed if the package has a prepare script before the
281           package is done installing.
282           Examples:
283
284           npm install mygithubuser/myproject
285           npm install github:mygithubuser/myproject
286
287       • npm            install            gist:[<githubname>/]<gistID>[#<com‐
288         mit-ish>|#semver:<semver>]:
289           Install the package at https://gist.github.com/gistID by attempting
290         to
291           clone it using git. The GitHub username associated with the gist is
292           optional and will not be saved in package.json.
293           As with regular git dependencies, dependencies and  devDependencies
294         will
295           be installed if the package has a prepare script before the package
296         is
297           done installing.
298           Example:
299
300           npm install gist:101a11beef
301
302       • npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]:
303           Install the package at https://bitbucket.org/bitbucketname/bitbuck‐
304         etrepo
305           by attempting to clone it using git.
306           If #<commit-ish> is provided, it will be used to clone exactly that
307           commit. If the commit-ish has the format #semver:<semver>, <semver>
308         can
309           be any valid semver range or exact version, and npm will  look  for
310         any tags
311           or  refs  matching  that range in the remote repository, much as it
312         would for a
313           registry dependency. If neither #<commit-ish>  or  #semver:<semver>
314         is
315           specified, then master is used.
316           As  with regular git dependencies, dependencies and devDependencies
317         will
318           be installed if the package has a prepare script before the package
319         is
320           done installing.
321           Example:
322
323           npm install bitbucket:mybitbucketuser/myproject
324
325       • npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]:
326           Install the package at https://gitlab.com/gitlabname/gitlabrepo
327           by attempting to clone it using git.
328           If #<commit-ish> is provided, it will be used to clone exactly that
329           commit. If the commit-ish has the format #semver:<semver>, <semver>
330         can
331           be any valid semver range or exact version, and npm will  look  for
332         any tags
333           or  refs  matching  that range in the remote repository, much as it
334         would for a
335           registry dependency. If neither #<commit-ish>  or  #semver:<semver>
336         is
337           specified, then master is used.
338           As  with regular git dependencies, dependencies and devDependencies
339         will
340           be installed if the package has a prepare script before the package
341         is
342           done installing.
343           Example:
344
345           npm install gitlab:mygitlabuser/myproject
346           npm install gitlab:myusr/myproj#semver:^5.0
347
348
349       You  may  combine  multiple  arguments and even multiple types of argu‐
350       ments.  For example:
351
352         npm install sax@">=0.1.0 <0.2.0" bench supervisor
353
354       The --tag argument will apply to all of the specified install  targets.
355       If  a  tag  with the given name exists, the tagged version is preferred
356       over newer versions.
357
358       The --dry-run argument will report in the usual way  what  the  install
359       would have done without actually installing anything.
360
361       The   --package-lock-only   argument   will   only   update  the  pack‐
362       age-lock.json, instead of checking node_modules and downloading  depen‐
363       dencies.
364
365       The  -f  or  --force  argument will force npm to fetch remote resources
366       even if a local copy exists on disk.
367
368         npm install sax --force
369
370   Configuration
371       See the npm help config help doc.  Many  of  the  configuration  params
372       have some effect on installation, since that's most of what npm does.
373
374       These  are  some  of  the  most common options related to installation.
375       <!-- AUTOGENERATED CONFIG DESCRIPTIONS  START  -->  <!--  automatically
376       generated,  do  not edit manually --> <!-- see lib/utils/config/defini‐
377       tions.js -->
378
379   save
380       • Default: true
381
382       • Type: Boolean
383
384
385       Save installed packages to a package.json file as dependencies.
386
387       When used with the npm rm command, removes the  dependency  from  pack‐
388       age.json.   <!-- automatically generated, do not edit manually --> <!--
389       see lib/utils/config/definitions.js -->
390
391
392   save-exact
393       • Default: false
394
395       • Type: Boolean
396
397
398       Dependencies saved to package.json will be  configured  with  an  exact
399       version  rather  than  using npm's default semver range operator.  <!--
400       automatically  generated,  do  not   edit   manually   -->   <!--   see
401       lib/utils/config/definitions.js -->
402
403
404   global
405       • Default: false
406
407       • Type: Boolean
408
409
410       Operates in "global" mode, so that packages are installed into the pre‐
411       fix folder instead of the current working directory. See npm help fold‐
412       ers for more on the differences in behavior.
413
414       • packages are installed into the {prefix}/lib/node_modules folder, in‐
415         stead of the current working directory.
416
417       • bin files are linked to {prefix}/bin
418
419       • man pages are linked to {prefix}/share/man
420
421       <!-- automatically  generated,  do  not  edit  manually  -->  <!--  see
422       lib/utils/config/definitions.js -->
423
424
425   global-style
426       • Default: false
427
428       • Type: Boolean
429
430
431       Causes  npm  to install the package into your local node_modules folder
432       with the same layout it uses with the global node_modules folder.  Only
433       your  direct dependencies will show in node_modules and everything they
434       depend on will be flattened in their node_modules folders.  This  obvi‐
435       ously  will  eliminate  some  deduping.  If  used with legacy-bundling,
436       legacy-bundling will be preferred.  <!--  automatically  generated,  do
437       not edit manually --> <!-- see lib/utils/config/definitions.js -->
438
439
440   legacy-bundling
441       • Default: false
442
443       • Type: Boolean
444
445
446       Causes  npm  to  install the package such that versions of npm prior to
447       1.4, such as the one included with node 0.8, can install  the  package.
448       This  eliminates all automatic deduping. If used with global-style this
449       option will be preferred.  <!-- automatically generated,  do  not  edit
450       manually --> <!-- see lib/utils/config/definitions.js -->
451
452
453   strict-peer-deps
454       • Default: false
455
456       • Type: Boolean
457
458
459       If set to true, and --legacy-peer-deps is not set, then any conflicting
460       peerDependencies will be treated as an install  failure,  even  if  npm
461       could reasonably guess the appropriate resolution based on non-peer de‐
462       pendency relationships.
463
464       By default, conflicting peerDependencies deep in the  dependency  graph
465       will  be  resolved using the nearest non-peer dependency specification,
466       even if doing so will result in some packages receiving a  peer  depen‐
467       dency outside the range set in their package's peerDependencies object.
468
469       When  such  and override is performed, a warning is printed, explaining
470       the conflict and the packages involved. If --strict-peer-deps  is  set,
471       then  this  warning is treated as a failure.  <!-- automatically gener‐
472       ated, do not edit manually --> <!-- see lib/utils/config/definitions.js
473       -->
474
475
476   package-lock
477       • Default: true
478
479       • Type: Boolean
480
481
482       If  set  to false, then ignore package-lock.json files when installing.
483       This will also prevent writing package-lock.json if save is true.
484
485       When package package-locks are disabled, automatic pruning of  extrane‐
486       ous  modules  will  also be disabled. To remove extraneous modules with
487       package-locks disabled use npm prune.  <!-- automatically generated, do
488       not edit manually --> <!-- see lib/utils/config/definitions.js -->
489
490
491   omit
492       • Default:  'dev'  if the NODE_ENV environment variable is set to 'pro‐
493         duction', otherwise empty.
494
495       • Type: "dev", "optional", or "peer" (can be set multiple times)
496
497
498       Dependency types to omit from the installation tree on disk.
499
500       Note that these dependencies are still resolved and added to the  pack‐
501       age-lock.json or npm-shrinkwrap.json file. They are just not physically
502       installed on disk.
503
504       If a package type appears in both the --include and --omit lists,  then
505       it will be included.
506
507       If  the  resulting omit list includes 'dev', then the NODE_ENV environ‐
508       ment variable will be set to 'production' for  all  lifecycle  scripts.
509       <!--  automatically  generated,  do  not  edit  manually  -->  <!-- see
510       lib/utils/config/definitions.js -->
511
512
513   ignore-scripts
514       • Default: false
515
516       • Type: Boolean
517
518
519       If true, npm does not run scripts specified in package.json files.
520
521       Note that commands explicitly intended to run a particular script, such
522       as  npm start, npm stop, npm restart, npm test, and npm run-script will
523       still run their intended script if ignore-scripts is set, but they will
524       not run any pre- or post-scripts.  <!-- automatically generated, do not
525       edit manually --> <!-- see lib/utils/config/definitions.js -->
526
527
528   audit
529       • Default: true
530
531       • Type: Boolean
532
533
534       When "true" submit audit reports alongside the current npm  command  to
535       the  default registry and all registries configured for scopes. See the
536       documentation for npm help audit for  details  on  what  is  submitted.
537       <!--  automatically  generated,  do  not  edit  manually  -->  <!-- see
538       lib/utils/config/definitions.js -->
539
540
541   bin-links
542       • Default: true
543
544       • Type: Boolean
545
546
547       Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
548       ecutables.
549
550       Set  to  false  to have it not do this. This can be used to work around
551       the fact that some file systems don't support symlinks, even on  osten‐
552       sibly Unix systems.  <!-- automatically generated, do not edit manually
553       --> <!-- see lib/utils/config/definitions.js -->
554
555
556   fund
557       • Default: true
558
559       • Type: Boolean
560
561
562       When "true" displays the message at the end of  each  npm  install  ac‐
563       knowledging  the  number  of  dependencies looking for funding. See npm
564       help npm fund for details.  <!-- automatically generated, do  not  edit
565       manually --> <!-- see lib/utils/config/definitions.js -->
566
567
568   dry-run
569       • Default: false
570
571       • Type: Boolean
572
573
574       Indicates  that  you  don't  want  npm  to make any changes and that it
575       should only report what it would have done. This can be passed into any
576       of  the  commands that modify your local installation, eg, install, up‐
577       date, dedupe, uninstall, as well as pack and publish.
578
579       Note: This is  NOT  honored  by  other  network  related  commands,  eg
580       dist-tags, owner, etc.  <!-- automatically generated, do not edit manu‐
581       ally --> <!-- see lib/utils/config/definitions.js -->
582
583
584   workspace
585       • Default:
586
587       • Type: String (can be set multiple times)
588
589
590       Enable running a command in the context of the configured workspaces of
591       the  current project while filtering by running only the workspaces de‐
592       fined by this configuration option.
593
594       Valid values for the workspace config are either:
595
596       • Workspace names
597
598       • Path to a workspace directory
599
600       • Path to a parent workspace directory (will result  in  selecting  all
601         workspaces within that folder)
602
603
604       When  set  for the npm init command, this may be set to the folder of a
605       workspace which does not yet exist, to create the folder and set it  up
606       as a brand new workspace within the project.
607
608       This  value  is  not  exported  to the environment for child processes.
609       <!-- automatically  generated,  do  not  edit  manually  -->  <!--  see
610       lib/utils/config/definitions.js -->
611
612
613   workspaces
614       • Default: null
615
616       • Type: null or Boolean
617
618
619       Set  to  true  to  run  the  command  in  the context of all configured
620       workspaces.
621
622       Explicitly setting this to false will cause commands  like  install  to
623       ignore workspaces altogether. When not set explicitly:
624
625       • Commands  that  operate  on  the  node_modules tree (install, update,
626         etc.)  will link workspaces into the node_modules folder. -  Commands
627         that  do other things (test, exec, publish, etc.) will operate on the
628         root project, unless one or more  workspaces  are  specified  in  the
629         workspace config.
630
631
632       This  value  is  not  exported  to the environment for child processes.
633       <!-- automatically  generated,  do  not  edit  manually  -->  <!--  see
634       lib/utils/config/definitions.js -->
635
636
637   include-workspace-root
638       • Default: false
639
640       • Type: Boolean
641
642
643       Include the workspace root when workspaces are enabled for a command.
644
645       When  false, specifying individual workspaces via the workspace config,
646       or all workspaces via the workspaces flag, will cause  npm  to  operate
647       only  on  the  specified workspaces, and not on the root project.  <!--
648       automatically  generated,  do  not   edit   manually   -->   <!--   see
649       lib/utils/config/definitions.js -->
650
651       <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
652
653
654   Algorithm
655       Given a package{dep} structure: A{B,C}, B{C}, C{D}, the npm install al‐
656       gorithm produces:
657
658         A
659         +-- B
660         +-- C
661         +-- D
662
663       That is, the dependency from B to C is satisfied by the fact that A al‐
664       ready  caused C to be installed at a higher level. D is still installed
665       at the top level because nothing conflicts with it.
666
667       For A{B,C}, B{C,D@1}, C{D@2}, this algorithm produces:
668
669         A
670         +-- B
671         +-- C
672            `-- D@2
673         +-- D@1
674
675       Because B's D@1 will be installed in the top-level, C now  has  to  in‐
676       stall  D@2  privately  for itself. This algorithm is deterministic, but
677       different trees may be produced if two dependencies are  requested  for
678       installation in a different order.
679
680       See  npm  help  folders for a more detailed description of the specific
681       folder structures that npm creates.
682
683   See Also
684       • npm help folders
685
686       • npm help update
687
688       • npm help audit
689
690       • npm help fund
691
692       • npm help link
693
694       • npm help rebuild
695
696       • npm help scripts
697
698       • npm help config
699
700       • npm help npmrc
701
702       • npm help registry
703
704       • npm help dist-tag
705
706       • npm help uninstall
707
708       • npm help shrinkwrap
709
710       • npm help package.json
711
712       • npm help workspaces
713
714
715
716
717                                 January 2022                   NPM-INSTALL(1)