npm-install(1)

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

NAME

6       npm-install - Install a package
7

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 <git-host>:<git-user>/<repo-name>
15         npm install <git repo url>
16         npm install <tarball file>
17         npm install <tarball url>
18         npm install <folder>
19
20         aliases: npm i, npm add
21         common options: [-P|--save-prod|-D|--save-dev|-O|--save-optional] [-E|--save-exact] [-B|--save-bundle] [--no-save] [--dry-run]
22

DESCRIPTION

24       This  command  installs a package, and any packages that it depends on.
25       If the package has a package-lock or shrinkwrap file, the  installation
26       of  dependencies  will  be  driven by that, with an npm-shrinkwrap.json
27       taking precedence if both files exist. See npm help 5 package-lock.json
28       and npm help shrinkwrap.
29
30       A package is:
31
32       · a)  a  folder  containing  a  program described by a npm help 5 pack‐
33         age.json file
34
35       · b) a gzipped tarball containing (a)
36
37       · c) a url that resolves to (b)
38
39       · d) a <name>@<version> that is published on the registry (see npm help
40         7 npm-registry) with (c)
41
42       · e) a <name>@<tag> (see npm help npm-dist-tag) that points to (d)
43
44       · f) a <name> that has a "latest" tag satisfying (e)
45
46       · g) a <git remote url> that resolves to (a)
47
48
49       Even if you never publish your package, you can still get a lot of ben‐
50       efits of using npm if you just want to write a node  program  (a),  and
51       perhaps  if  you  also  want  to be able to easily install it elsewhere
52       after packing it up into a tarball (b).
53
54       · npm install (in package directory, no arguments):
55           Install the dependencies in the local node_modules folder.
56           In global mode (ie, with -g or --global appended to the command),
57           it installs the current package context (ie, the current working
58           directory) as a global package.
59           By default, npm install will install all modules listed  as  depen‐
60         dencies
61           in npm help 5 package.json.
62           With  the --production flag (or when the NODE_ENV environment vari‐
63         able
64           is set to production), npm will not install modules listed in
65           devDependencies.  NOTE: The --production  flag  has  no  particular
66         meaning when adding a
67           dependency to a project.
68
69
70       · npm install <folder>:
71           Install  the  package  in the directory as a symlink in the current
72         project.
73           Its dependencies will be installed before it's linked. If  <folder>
74         sits
75           inside the root of your project, its dependencies may be hoisted to
76         the
77           toplevel node_modules as they would for other  types  of  dependen‐
78         cies.
79
80       · npm install <tarball file>:
81           Install  a package that is sitting on the filesystem.  Note: if you
82         just want
83           to link a dev directory into your npm root, you can  do  this  more
84         easily by
85           using npm link.
86           Tarball requirements:
87
88       · The filename must use .tar, .tar.gz, or .tgz as the extension.
89
90       · The  package contents should reside in a subfolder inside the tarball
91         (usually it is called package/). npm strips one directory layer  when
92         installing  the  package (an equivalent of tar x --strip-components=1
93         is run).
94
95       · The package must contain a package.json file with  name  and  version
96         properties.  Example:
97
98         npm install ./package.tgz
99
100
101       · npm install <tarball url>:
102           Fetch  the  tarball  url, and then install it.  In order to distin‐
103         guish between
104           this and other options, the argument must start with  "http://"  or
105         "https://"
106           Example:
107
108             npm install https://github.com/indexzero/forever/tarball/v0.5.6
109
110       · npm install [<@scope>/]<name>:
111           Do a <name>@<tag> install, where <tag> is the "tag" config. (See
112           npm help 7 npm-config. The config's default value is latest.)
113           In  most cases, this will install the version of the modules tagged
114         as
115           latest on the npm registry.
116           Example:
117
118             npm install sax
119         npm  install  saves  any  specified  packages  into  dependencies  by
120       default.
121         Additionally, you can control where and how they get saved with some
122         additional flags:
123
124       · -P,  --save-prod:  Package  will appear in your dependencies. This is
125         the
126
127                        default unless `-D` or `-O` are present.
128
129       · -D, --save-dev: Package will appear in your devDependencies.
130
131       · -O, --save-optional: Package will appear  in  your  optionalDependen‐
132         cies.
133
134       · --no-save:  Prevents  saving  to dependencies.  When using any of the
135         above options to save dependencies to your  package.json,  there  are
136         two additional, optional flags:
137
138       · -E, --save-exact: Saved dependencies will be configured with an exact
139         version rather than using npm's default semver range operator.
140
141       · -B, --save-bundle: Saved dependencies will also be added to your bun‐
142         dleDependencies list.  Further, if you have an npm-shrinkwrap.json or
143         package-lock.json then it  will  be  updated  as  well.   <scope>  is
144         optional. The package will be downloaded from the registry associated
145         with the specified scope. If no registry is associated with the given
146         scope  the  default  registry  is  assumed. See npm help 7 npm-scope.
147         Note: if you do not include the @-symbol on your scope name, npm will
148         interpret  this  as  a  GitHub  repository instead, see below. Scopes
149         names must also be followed by a slash.  Examples:
150
151         npm install sax
152         npm install githubname/reponame
153         npm install @myorg/privatepackage
154         npm install node-tap --save-dev
155         npm install dtrace-provider --save-optional
156         npm install readable-stream --save-exact
157         npm install ansi-regex --save-bundle
158
159
160
161         **Note**: If there is a file or folder named `<name>` in the current
162         working directory, then it will try to install that, and only try to
163         fetch the package by name if it is not valid.
164
165       · npm install [<@scope>/]<name>@<tag>:
166           Install the version of the package that is referenced by the speci‐
167         fied tag.
168           If  the  tag  does not exist in the registry data for that package,
169         then this
170           will fail.
171           Example:
172
173             npm install sax@latest
174             npm install @myorg/mypackage@latest
175
176       · npm install [<@scope>/]<name>@<version>:
177           Install the specified version of the package.  This  will  fail  if
178         the
179           version has not been published to the registry.
180           Example:
181
182             npm install sax@0.1.1
183             npm install @myorg/privatepackage@1.5.0
184
185       · npm install [<@scope>/]<name>@<version range>:
186           Install  a  version  of  the package matching the specified version
187         range.  This
188           will follow the same rules for resolving dependencies described  in
189         npm help 5 package.json.
190           Note  that  most  version ranges must be put in quotes so that your
191         shell will
192           treat it as a single argument.
193           Example:
194
195             npm install sax@">=0.1.0 <0.2.0"
196             npm install @myorg/privatepackage@">=0.1.0 <0.2.0"
197
198       · npm install <git remote url>:
199           Installs the package from the hosted git provider, cloning it  with
200         git.
201           For a full git remote url, only that URL will be attempted.
202
203             <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
204         <protocol> is one of git, git+ssh, git+http, git+https, or
205         git+file.
206         If #<commit-ish> is provided, it will be used to clone exactly that
207         commit.  If  the commit-ish has the format #semver:<semver>, <semver>
208       can
209         be any valid semver range or exact version, and npm will look for any
210       tags
211         or  refs  matching  that  range  in the remote repository, much as it
212       would for a
213         registry dependency. If neither #<commit-ish> or #semver:<semver> is
214         specified, then the default branch of the repository is used.
215         If the repository makes use of submodules, those submodules  will  be
216       cloned
217         as well.
218         If the package being installed contains a prepare script, its
219         dependencies and devDependencies will be installed, and the prepare
220         script will be run, before the package is packaged and installed.
221         The  following  git  environment  variables are recognized by npm and
222       will be
223         added to the environment when running git:
224
225       · GIT_ASKPASS
226
227       · GIT_EXEC_PATH
228
229       · GIT_PROXY_COMMAND
230
231       · GIT_SSH
232
233       · GIT_SSH_COMMAND
234
235       · GIT_SSL_CAINFO
236
237       · GIT_SSL_NO_VERIFY See the git man page for details.  Examples:
238
239         npm install git+ssh://git@github.com:npm/cli.git#v1.0.27
240         npm install git+ssh://git@github.com:npm/cli#semver:^5.0
241         npm install git+https://isaacs@github.com/npm/cli.git
242         npm install git://github.com/npm/cli.git#v1.0.27
243         GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git
244
245
246       · npm install <githubname>/<githubrepo>[#<commit-ish>]:
247
248       · npm install github:<githubname>/<githubrepo>[#<commit-ish>]:
249           Install the package at https://github.com/githubname/githubrepo by
250           attempting to clone it using git.
251           If #<commit-ish> is provided, it will be used to clone exactly that
252           commit. If the commit-ish has the format #semver:<semver>, <semver>
253         can
254           be  any  valid semver range or exact version, and npm will look for
255         any tags
256           or refs matching that range in the remote repository,  much  as  it
257         would for a
258           registry  dependency.  If neither #<commit-ish> or #semver:<semver>
259         is
260           specified, then master is used.
261           As with regular git dependencies, dependencies and  devDependencies
262         will
263           be  installed if the package has a prepare script, before the pack‐
264         age is
265           done installing.
266           Examples:
267
268             npm install mygithubuser/myproject
269             npm install github:mygithubuser/myproject
270
271       · npm            install            gist:[<githubname>/]<gistID>[#<com‐
272         mit-ish>|#semver:<semver>]:
273           Install the package at https://gist.github.com/gistID by attempting
274         to
275           clone it using git. The GitHub username associated with the gist is
276           optional and will not be saved in package.json.
277           As with regular git dependencies, dependencies and  devDependencies
278         will
279           be  installed if the package has a prepare script, before the pack‐
280         age is
281           done installing.
282           Example:
283
284             npm install gist:101a11beef
285
286       · npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]:
287           Install the package at https://bitbucket.org/bitbucketname/bitbuck‐
288         etrepo
289           by attempting to clone it using git.
290           If #<commit-ish> is provided, it will be used to clone exactly that
291           commit. If the commit-ish has the format #semver:<semver>, <semver>
292         can
293           be any valid semver range or exact version, and npm will  look  for
294         any tags
295           or  refs  matching  that range in the remote repository, much as it
296         would for a
297           registry dependency. If neither #<commit-ish>  or  #semver:<semver>
298         is
299           specified, then master is used.
300           As  with regular git dependencies, dependencies and devDependencies
301         will
302           be installed if the package has a prepare script, before the  pack‐
303         age is
304           done installing.
305           Example:
306
307             npm install bitbucket:mybitbucketuser/myproject
308
309       · npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]:
310           Install the package at https://gitlab.com/gitlabname/gitlabrepo
311           by attempting to clone it using git.
312           If #<commit-ish> is provided, it will be used to clone exactly that
313           commit. If the commit-ish has the format #semver:<semver>, <semver>
314         can
315           be any valid semver range or exact version, and npm will  look  for
316         any tags
317           or  refs  matching  that range in the remote repository, much as it
318         would for a
319           registry dependency. If neither #<commit-ish>  or  #semver:<semver>
320         is
321           specified, then master is used.
322           As  with regular git dependencies, dependencies and devDependencies
323         will
324           be installed if the package has a prepare script, before the  pack‐
325         age is
326           done installing.
327           Example:
328
329             npm install gitlab:mygitlabuser/myproject
330             npm install gitlab:myusr/myproj#semver:^5.0
331
332
333       You  may  combine  multiple arguments, and even multiple types of argu‐
334       ments.  For example:
335
336         npm install sax@">=0.1.0 <0.2.0" bench supervisor
337
338       The --tag argument will apply to all of the specified install  targets.
339       If  a  tag  with the given name exists, the tagged version is preferred
340       over newer versions.
341
342       The --dry-run argument will report in the usual way  what  the  install
343       would have done without actually installing anything.
344
345       The   --package-lock-only   argument   will   only   update  the  pack‐
346       age-lock.json, instead of checking node_modules and downloading  depen‐
347       dencies.
348
349       The  -f  or  --force  argument will force npm to fetch remote resources
350       even if a local copy exists on disk.
351
352         npm install sax --force
353
354       The -g or --global argument will cause npm to install the package glob‐
355       ally rather than locally.  See npm help 5 npm-folders.
356
357       The  --global-style argument will cause npm to install the package into
358       your local node_modules folder with the same layout it  uses  with  the
359       global  node_modules folder. Only your direct dependencies will show in
360       node_modules and everything they depend on will be flattened  in  their
361       node_modules folders. This obviously will eliminate some deduping.
362
363       The --ignore-scripts argument will cause npm to not execute any scripts
364       defined in the package.json. See npm help 7 npm-scripts.
365
366       The --legacy-bundling argument will cause npm to  install  the  package
367       such  that  versions of npm prior to 1.4, such as the one included with
368       node 0.8, can install the package. This eliminates all automatic dedup‐
369       ing.
370
371       The  --link  argument  will  cause npm to link global installs into the
372       local space in some cases.
373
374       The --no-bin-links argument will prevent npm from creating symlinks for
375       any binaries the package might contain.
376
377       The  --no-optional  argument  will  prevent  optional dependencies from
378       being installed.
379
380       The --no-shrinkwrap argument, which will ignore  an  available  package
381       lock or shrinkwrap file and use the package.json instead.
382
383       The  --no-package-lock  argument will prevent npm from creating a pack‐
384       age-lock.json file.  When running with package-lock's disabled npm will
385       not automatically prune your node modules when installing.
386
387       The  --nodedir=/path/to/node/source argument will allow npm to find the
388       node source code so that npm can compile native modules.
389
390       The --only={prod[uction]|dev[elopment]} argument will cause either only
391       devDependencies  or only non-devDependencies to be installed regardless
392       of the NODE_ENV.
393
394       The --no-audit argument can be used to disable sending of audit reports
395       to  the  configured  registries.  See npm help npm-audit for details on
396       what is sent.
397
398       See npm help 7 npm-config.  Many of the configuration params have  some
399       effect on installation, since that's most of what npm does.
400

ALGORITHM

402       To install a package, npm uses the following algorithm:
403
404         load the existing node_modules tree from disk
405         clone the tree
406         fetch the package.json and assorted metadata and add it to the clone
407         walk the clone and add any missing dependencies
408           dependencies will be added as close to the top as is possible
409           without breaking any other modules
410         compare the original tree with the cloned tree and make a list of
411         actions to take to convert one to the other
412         execute all of the actions, deepest first
413           kinds of actions are install, update, remove and move
414
415       For  this  package{dep}  structure:  A{B,C}, B{C}, C{D}, this algorithm
416       produces:
417
418         A
419         +-- B
420         +-- C
421         +-- D
422
423       That is, the dependency from B to C is satisfied by  the  fact  that  A
424       already  caused  C  to  be  installed  at  a  higher  level. D is still
425       installed at the top level because nothing conflicts with it.
426
427       For A{B,C}, B{C,D@1}, C{D@2}, this algorithm produces:
428
429         A
430         +-- B
431         +-- C
432            `-- D@2
433         +-- D@1
434
435       Because B's D@1 will be installed in  the  top  level,  C  now  has  to
436       install  D@2 privately for itself. This algorithm is deterministic, but
437       different trees may be produced if two dependencies are  requested  for
438       installation in a different order.
439
440       See  npm help 5 folders for a more detailed description of the specific
441       folder structures that npm creates.
442
443   Limitations of npm's Install Algorithm
444       npm will refuse to install any package with an identical  name  to  the
445       current  package.  This can be overridden with the --force flag, but in
446       most cases can simply be addressed by changing the local package name.
447
448       There are some very rare and pathological edge-cases where a cycle  can
449       cause  npm  to try to install a never-ending tree of packages.  Here is
450       the simplest case:
451
452         A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...
453
454       where A is some version of a package, and A' is a different version  of
455       the  same  package.  Because B depends on a different version of A than
456       the one that is already in the tree, it must install a  separate  copy.
457       The  same  is true of A', which must install B'.  Because B' depends on
458       the original version of A, which has been overridden, the  cycle  falls
459       into infinite regress.
460
461       To  avoid this situation, npm flat-out refuses to install any name@ver‐
462       sion that is already present anywhere in the  tree  of  package  folder
463       ancestors.  A more correct, but more complex, solution would be to sym‐
464       link the existing version into the new location.  If this ever  affects
465       a real use-case, it will be investigated.
466

NAME

SYNOPSIS

DESCRIPTION

ALGORITHM

SEE ALSO