1NPM-INSTALL(1) NPM-INSTALL(1)
2
6 npm-install - Install a package
7
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 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
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 A package is:
31 · a) a folder containing a program described by a npm help 5 pack‐
33 age.json file
34 · b) a gzipped tarball containing (a)
36 · c) a url that resolves to (b)
38 · d) a <name>@<version> that is published on the registry (see npm help
40 7 npm-registry) with (c)
41 · e) a <name>@<tag> (see npm help npm-dist-tag) that points to (d)
43 · f) a <name> that has a "latest" tag satisfying (e)
45 · g) a <git remote url> that resolves to (a)
47 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 · 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 · 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 · 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 · The filename must use .tar, .tar.gz, or .tgz as the extension.
89 · The package contents should reside in a subfolder inside the tar‐
91 ball (usually it is called package/). npm strips one directory
92 layer when installing the package (an equivalent of tar x
93 --strip-components=1 is run).
94 · The package must contain a package.json file with name and version
96 properties. Example:
97 npm install ./package.tgz
99 · 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 npm install https://github.com/indexzero/forever/tarball/v0.5.6
109 · 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 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 · -P, --save-prod: Package will appear in your dependencies.
125 This is the
126 default unless `-D` or `-O` are present.
128 · -D, --save-dev: Package will appear in your devDependencies.
130 · -O, --save-optional: Package will appear in your optionalDe‐
132 pendencies.
133 · --no-save: Prevents saving to dependencies. When using any of
135 the above options to save dependencies to your package.json,
136 there are two additional, optional flags:
137 · -E, --save-exact: Saved dependencies will be configured with
139 an exact version rather than using npm's default semver range
140 operator.
141 · -B, --save-bundle: Saved dependencies will also be added to
143 your bundleDependencies list. Further, if you have an
144 npm-shrinkwrap.json or package-lock.json then it will be
145 updated as well. <scope> is optional. The package will be
146 downloaded from the registry associated with the specified
147 scope. If no registry is associated with the given scope the
148 default registry is assumed. See npm help 7 npm-scope. Note:
149 if you do not include the @-symbol on your scope name, npm
150 will interpret this as a GitHub repository instead, see below.
151 Scopes names must also be followed by a slash. Examples:
152 npm install sax
154 npm install githubname/reponame
155 npm install @myorg/privatepackage
156 npm install node-tap --save-dev
157 npm install dtrace-provider --save-optional
158 npm install readable-stream --save-exact
159 npm install ansi-regex --save-bundle
160 **Note**: If there is a file or folder named `<name>` in the current
164 working directory, then it will try to install that, and only try to
165 fetch the package by name if it is not valid.
166 · npm install [<@scope>/]<name>@<tag>:
168 Install the version of the package that is referenced by the speci‐
169 fied tag.
170 If the tag does not exist in the registry data for that package,
171 then this
172 will fail.
173 Example:
174 npm install sax@latest
176 npm install @myorg/mypackage@latest
177 · npm install [<@scope>/]<name>@<version>:
179 Install the specified version of the package. This will fail if
180 the
181 version has not been published to the registry.
182 Example:
183 npm install sax@0.1.1
185 npm install @myorg/privatepackage@1.5.0
186 · npm install [<@scope>/]<name>@<version range>:
188 Install a version of the package matching the specified version
189 range. This
190 will follow the same rules for resolving dependencies described in
191 npm help 5 package.json.
192 Note that most version ranges must be put in quotes so that your
193 shell will
194 treat it as a single argument.
195 Example:
196 npm install sax@">=0.1.0 <0.2.0"
198 npm install @myorg/privatepackage@">=0.1.0 <0.2.0"
199 · npm install <git remote url>:
201 Installs the package from the hosted git provider, cloning it with
202 git.
203 For a full git remote url, only that URL will be attempted.
204 <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
206 <protocol> is one of git, git+ssh, git+http, git+https, or
207 git+file.
208 If #<commit-ish> is provided, it will be used to clone exactly that
209 commit. If the commit-ish has the format #semver:<semver>, <semver>
210 can
211 be any valid semver range or exact version, and npm will look for any
212 tags
213 or refs matching that range in the remote repository, much as it
214 would for a
215 registry dependency. If neither #<commit-ish> or #semver:<semver> is
216 specified, then the default branch of the repository is used.
217 If the repository makes use of submodules, those submodules will be
218 cloned
219 as well.
220 If the package being installed contains a prepare script, its
221 dependencies and devDependencies will be installed, and the prepare
222 script will be run, before the package is packaged and installed.
223 The following git environment variables are recognized by npm and
224 will be
225 added to the environment when running git:
226 · GIT_ASKPASS
228 · GIT_EXEC_PATH
230 · GIT_PROXY_COMMAND
232 · GIT_SSH
234 · GIT_SSH_COMMAND
236 · GIT_SSL_CAINFO
238 · GIT_SSL_NO_VERIFY See the git man page for details. Examples:
240 npm install git+ssh://git@github.com:npm/cli.git#v1.0.27
242 npm install git+ssh://git@github.com:npm/cli#semver:^5.0
243 npm install git+https://isaacs@github.com/npm/cli.git
244 npm install git://github.com/npm/cli.git#v1.0.27
245 GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git
246 · npm install <githubname>/<githubrepo>[#<commit-ish>]:
249 · npm install github:<githubname>/<githubrepo>[#<commit-ish>]:
251 Install the package at https://github.com/githubname/githubrepo by
252 attempting to clone it using git.
253 If #<commit-ish> is provided, it will be used to clone exactly that
254 commit. If the commit-ish has the format #semver:<semver>, <semver>
255 can
256 be any valid semver range or exact version, and npm will look for
257 any tags
258 or refs matching that range in the remote repository, much as it
259 would for a
260 registry dependency. If neither #<commit-ish> or #semver:<semver>
261 is
262 specified, then master is used.
263 As with regular git dependencies, dependencies and devDependencies
264 will
265 be installed if the package has a prepare script, before the pack‐
266 age is
267 done installing.
268 Examples:
269 npm install mygithubuser/myproject
271 npm install github:mygithubuser/myproject
272 · npm install gist:[<githubname>/]<gistID>[#<com‐
274 mit-ish>|#semver:<semver>]:
275 Install the package at https://gist.github.com/gistID by attempting
276 to
277 clone it using git. The GitHub username associated with the gist is
278 optional and will not be saved in package.json.
279 As with regular git dependencies, dependencies and devDependencies
280 will
281 be installed if the package has a prepare script, before the pack‐
282 age is
283 done installing.
284 Example:
285 npm install gist:101a11beef
287 · npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]:
289 Install the package at https://bitbucket.org/bitbucketname/bitbuck‐
290 etrepo
291 by attempting to clone it using git.
292 If #<commit-ish> is provided, it will be used to clone exactly that
293 commit. If the commit-ish has the format #semver:<semver>, <semver>
294 can
295 be any valid semver range or exact version, and npm will look for
296 any tags
297 or refs matching that range in the remote repository, much as it
298 would for a
299 registry dependency. If neither #<commit-ish> or #semver:<semver>
300 is
301 specified, then master is used.
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 npm install bitbucket:mybitbucketuser/myproject
310 · npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]:
312 Install the package at https://gitlab.com/gitlabname/gitlabrepo
313 by attempting to clone it using git.
314 If #<commit-ish> is provided, it will be used to clone exactly that
315 commit. If the commit-ish has the format #semver:<semver>, <semver>
316 can
317 be any valid semver range or exact version, and npm will look for
318 any tags
319 or refs matching that range in the remote repository, much as it
320 would for a
321 registry dependency. If neither #<commit-ish> or #semver:<semver>
322 is
323 specified, then master is used.
324 As with regular git dependencies, dependencies and devDependencies
325 will
326 be installed if the package has a prepare script, before the pack‐
327 age is
328 done installing.
329 Example:
330 npm install gitlab:mygitlabuser/myproject
332 npm install gitlab:myusr/myproj#semver:^5.0
333 You may combine multiple arguments, and even multiple types of argu‐
336 ments. For example:
337 npm install sax@">=0.1.0 <0.2.0" bench supervisor
339 The --tag argument will apply to all of the specified install targets.
341 If a tag with the given name exists, the tagged version is preferred
342 over newer versions.
343 The --dry-run argument will report in the usual way what the install
345 would have done without actually installing anything.
346 The --package-lock-only argument will only update the pack‐
348 age-lock.json, instead of checking node_modules and downloading depen‐
349 dencies.
350 The -f or --force argument will force npm to fetch remote resources
352 even if a local copy exists on disk.
353 npm install sax --force
355 The -g or --global argument will cause npm to install the package glob‐
357 ally rather than locally. See npm help 5 npm-folders.
358 The --global-style argument will cause npm to install the package into
360 your local node_modules folder with the same layout it uses with the
361 global node_modules folder. Only your direct dependencies will show in
362 node_modules and everything they depend on will be flattened in their
363 node_modules folders. This obviously will eliminate some deduping.
364 The --ignore-scripts argument will cause npm to not execute any scripts
366 defined in the package.json. See npm help 7 npm-scripts.
367 The --legacy-bundling argument will cause npm to install the package
369 such that versions of npm prior to 1.4, such as the one included with
370 node 0.8, can install the package. This eliminates all automatic dedup‐
371 ing.
372 The --link argument will cause npm to link global installs into the
374 local space in some cases.
375 The --no-bin-links argument will prevent npm from creating symlinks for
377 any binaries the package might contain.
378 The --no-optional argument will prevent optional dependencies from
380 being installed.
381 The --no-shrinkwrap argument, which will ignore an available package
383 lock or shrinkwrap file and use the package.json instead.
384 The --no-package-lock argument will prevent npm from creating a pack‐
386 age-lock.json file. When running with package-lock's disabled npm will
387 not automatically prune your node modules when installing.
388 The --nodedir=/path/to/node/source argument will allow npm to find the
390 node source code so that npm can compile native modules.
391 The --only={prod[uction]|dev[elopment]} argument will cause either only
393 devDependencies or only non-devDependencies to be installed regardless
394 of the NODE_ENV.
395 The --no-audit argument can be used to disable sending of audit reports
397 to the configured registries. See npm help npm-audit for details on
398 what is sent.
399 See npm help 7 npm-config. Many of the configuration params have some
401 effect on installation, since that's most of what npm does.
402
404 To install a package, npm uses the following algorithm:
405 load the existing node_modules tree from disk
407 clone the tree
408 fetch the package.json and assorted metadata and add it to the clone
409 walk the clone and add any missing dependencies
410 dependencies will be added as close to the top as is possible
411 without breaking any other modules
412 compare the original tree with the cloned tree and make a list of
413 actions to take to convert one to the other
414 execute all of the actions, deepest first
415 kinds of actions are install, update, remove and move
416 For this package{dep} structure: A{B,C}, B{C}, C{D}, this algorithm
418 produces:
419 A
421 +-- B
422 +-- C
423 +-- D
424 That is, the dependency from B to C is satisfied by the fact that A
426 already caused C to be installed at a higher level. D is still
427 installed at the top level because nothing conflicts with it.
428 For A{B,C}, B{C,D@1}, C{D@2}, this algorithm produces:
430 A
432 +-- B
433 +-- C
434 `-- D@2
435 +-- D@1
436 Because B's D@1 will be installed in the top level, C now has to
438 install D@2 privately for itself. This algorithm is deterministic, but
439 different trees may be produced if two dependencies are requested for
440 installation in a different order.
441 See npm help 5 folders for a more detailed description of the specific
443 folder structures that npm creates.
444 Limitations of npm's Install Algorithm
446 npm will refuse to install any package with an identical name to the
447 current package. This can be overridden with the --force flag, but in
448 most cases can simply be addressed by changing the local package name.
449 There are some very rare and pathological edge-cases where a cycle can
451 cause npm to try to install a never-ending tree of packages. Here is
452 the simplest case:
453 A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...
455 where A is some version of a package, and A' is a different version of
457 the same package. Because B depends on a different version of A than
458 the one that is already in the tree, it must install a separate copy.
459 The same is true of A', which must install B'. Because B' depends on
460 the original version of A, which has been overridden, the cycle falls
461 into infinite regress.
462 To avoid this situation, npm flat-out refuses to install any name@ver‐
464 sion that is already present anywhere in the tree of package folder
465 ancestors. A more correct, but more complex, solution would be to sym‐
466 link the existing version into the new location. If this ever affects
467 a real use-case, it will be investigated.
468
470 · npm help 5 folders
471 · npm help update
473 · npm help audit
475 · npm help link
477 · npm help rebuild
479 · npm help 7 scripts
481 · npm help build
483 · npm help config
485 · npm help 7 config
487 · npm help 5 npmrc
489 · npm help 7 registry
491 · npm help dist-tag
493 · npm help uninstall
495 · npm help shrinkwrap
497 · npm help 5 package.json
499 October 2019 NPM-INSTALL(1)