1NPM-INSTALL(1) NPM-INSTALL(1)
2
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 <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 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 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 A package is:
32 · a) a folder containing a program described by a npm help package.json
34 file
35 · b) a gzipped tarball containing (a)
37 · c) a url that resolves to (b)
39 · d) a <name>@<version> that is published on the registry (see npm help
41 registry) with (c)
42 · e) a <name>@<tag> (see npm help dist-tag) that points to (d)
44 · f) a <name> that has a "latest" tag satisfying (e)
46 · g) a <git remote url> that resolves to (a)
48 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 · 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 · 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 · 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 · The filename must use .tar, .tar.gz, or .tgz as the extension.
93 · 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 · The package must contain a package.json file with name and version
100 properties. Example:
101 npm install ./package.tgz
103 · 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 npm install https://github.com/indexzero/forever/tarball/v0.5.6
113 · 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 npm install sax
123 · 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 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 `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 * `-P, --save-prod`: Package will appear in your `dependencies`. This is the
146 default unless `-D` or `-O` are present.
147 * `-D, --save-dev`: Package will appear in your `devDependencies`.
149 * `-O, --save-optional`: Package will appear in your `optionalDependencies`.
151 * `--no-save`: Prevents saving to `dependencies`.
153 When using any of the above options to save dependencies to your
155 package.json, there are two additional, optional flags:
156 * `-E, --save-exact`: Saved dependencies will be configured with an
158 exact version rather than using npm's default semver range
159 operator.
160 * `-B, --save-bundle`: Saved dependencies will also be added to your `bundleDependencies` list.
162 Further, if you have an `npm-shrinkwrap.json` or `package-lock.json` then it
164 will be updated as well.
165 `<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 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 Examples:
175 ```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 **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 · 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 npm install sax@latest
199 npm install @myorg/mypackage@latest
200 · 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 npm install sax@0.1.1
208 npm install @myorg/privatepackage@1.5.0
209 · 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 npm install sax@">=0.1.0 <0.2.0"
221 npm install @myorg/privatepackage@">=0.1.0 <0.2.0"
222 · 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 <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 · GIT_ASKPASS
251 · GIT_EXEC_PATH
253 · GIT_PROXY_COMMAND
255 · GIT_SSH
257 · GIT_SSH_COMMAND
259 · GIT_SSL_CAINFO
261 · GIT_SSL_NO_VERIFY See the git man page for details. Examples:
263 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 · npm install <githubname>/<githubrepo>[#<commit-ish>]:
272 · 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 npm install mygithubuser/myproject
294 npm install github:mygithubuser/myproject
295 · 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 npm install gist:101a11beef
310 · 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 npm install bitbucket:mybitbucketuser/myproject
333 · 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 npm install gitlab:mygitlabuser/myproject
355 npm install gitlab:myusr/myproj#semver:^5.0
356 You may combine multiple arguments, and even multiple types of argu‐
359 ments. For example:
360 npm install sax@">=0.1.0 <0.2.0" bench supervisor
362 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 The --dry-run argument will report in the usual way what the install
368 would have done without actually installing anything.
369 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 The -f or --force argument will force npm to fetch remote resources
375 even if a local copy exists on disk.
376 npm install sax --force
378 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 The -g or --global argument will cause npm to install the package glob‐
384 ally rather than locally. See npm help folders.
385 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 The --ignore-scripts argument will cause npm to not execute any scripts
393 defined in the package.json. See npm help scripts.
394 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 The --link argument will cause npm to link global installs into the
401 local space in some cases.
402 The --no-bin-links argument will prevent npm from creating symlinks for
404 any binaries the package might contain.
405 The --no-optional argument will prevent optional dependencies from
407 being installed.
408 The --no-shrinkwrap argument, which will ignore an available package
410 lock or shrinkwrap file and use the package.json instead.
411 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 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 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 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 See npm help config. Many of the configuration params have some effect
428 on installation, since that's most of what npm does.
429 Algorithm
431 To install a package, npm uses the following algorithm:
432 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 For this package{dep} structure: A{B,C}, B{C}, C{D}, this algorithm
445 produces:
446 A
448 +-- B
449 +-- C
450 +-- D
451 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 For A{B,C}, B{C,D@1}, C{D@2}, this algorithm produces:
457 A
459 +-- B
460 +-- C
461 `-- D@2
462 +-- D@1
463 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 See npm help folders for a more detailed description of the specific
470 folder structures that npm creates.
471 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 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 A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...
482 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 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 See Also
497 · npm help folders
498 · npm help update
500 · npm help audit
502 · npm help fund
504 · npm help link
506 · npm help rebuild
508 · npm help scripts
510 · npm help build
512 · npm help config
514 · npm help npmrc
516 · npm help registry
518 · npm help dist-tag
520 · npm help uninstall
522 · npm help shrinkwrap
524 · npm help package.json
526 February 2021 NPM-INSTALL(1)