1NPM-INSTALL(1) NPM-INSTALL(1)
2
6 npm-install - Install a package
7 Synopsis
9 npm install [<package-spec> ...]
10 aliases: add, i, in, ins, inst, insta, instal, isnt, isnta, isntal, isntall
12 Description
14 This command installs a package and any packages that it depends on. If
15 the package has a package-lock, or an npm shrinkwrap file, or a yarn
16 lock file, the installation of dependencies will be driven by that, re‐
17 specting the following order of precedence:
18 • npm-shrinkwrap.json
20 • package-lock.json
22 • yarn.lock
24 See package-lock.json ⟨/configuring-npm/package-lock-json⟩ and npm help
27 shrinkwrap.
28 A package is:
30 • a) a folder containing a program described by a package.json ⟨/con‐
32 figuring-npm/package-json⟩ file
33 • b) a gzipped tarball containing (a)
35 • c) a url that resolves to (b)
37 • d) a <name>@<version> that is published on the registry (see npm
39 help registry) with (c)
40 • e) a <name>@<tag> (see npm help dist-tag) that points to (d)
42 • f) a <name> that has a "latest" tag satisfying (e)
44 • g) a <git remote url> that resolves to (a)
46 Even if you never publish your package, you can still get a lot of ben‐
49 efits of using npm if you just want to write a node program (a), and
50 perhaps if you also want to be able to easily install it elsewhere af‐
51 ter packing it up into a tarball (b).
52 • npm install (in a package directory, no arguments):
54 Install the dependencies to the local node_modules folder.
56 In global mode (ie, with -g or --global appended to the command), it
58 installs the current package context (ie, the current working direc‐
59 tory) as a global package.
60 By default, npm install will install all modules listed as dependencies
62 in package.json ⟨/configuring-npm/package-json⟩.
63 With the --production flag (or when the NODE_ENV environment variable
65 is set to production), npm will not install modules listed in devDepen‐
66 dencies. To install all modules listed in both dependencies and devDe‐
67 pendencies when NODE_ENV environment variable is set to production, you
68 can use --production=false.
69 NOTE: The --production flag has no particular meaning when adding a
71 dependency to a project.
72 • npm install <folder>:
75 If <folder> sits inside the root of your project, its dependencies will
77 be installed and may be hoisted to the top-level node_modules as they
78 would for other types of dependencies. If <folder> sits outside the
79 root of your project, npm will not install the package dependencies in
80 the directory <folder>, but it will create a symlink to <folder>.
81 NOTE: If you want to install the content of a directory like a
83 package from the registry instead of creating a link, you would
84 need to use the --install-links option.
85 Example:
88 npm install ../../other-package --install-links
90 npm install ./sub-package
91 • npm install <tarball file>:
93 Install a package that is sitting on the filesystem. Note: if you just
95 want to link a dev directory into your npm root, you can do this more
96 easily by using npm help link.
97 Tarball requirements:
99 • The filename must use .tar, .tar.gz, or .tgz as the extension.
101 • The package contents should reside in a subfolder inside the
103 tarball (usually it is called package/). npm strips one direc‐
104 tory layer when installing the package (an equivalent of tar x
105 --strip-components=1 is run).
106 • The package must contain a package.json file with name and ver‐
108 sion properties.
109 Example:
112 npm install ./package.tgz
114 • npm install <tarball url>:
116 Fetch the tarball url, and then install it. In order to distinguish be‐
118 tween this and other options, the argument must start with "http://" or
119 "https://"
120 Example:
122 npm install https://github.com/indexzero/forever/tarball/v0.5.6
124 • npm install [<@scope>/]<name>:
126 Do a <name>@<tag> install, where <tag> is the "tag" config. (See config
128 ⟨/using-npm/config#tag⟩. The config's default value is latest.)
129 In most cases, this will install the version of the modules tagged as
131 latest on the npm registry.
132 Example:
134 npm install sax
136 npm install saves any specified packages into dependencies by default.
138 Additionally, you can control where and how they get saved with some
139 additional flags:
140 • -P, --save-prod: Package will appear in your dependencies. This
142 is the default unless -D or -O are present.
143 • -D, --save-dev: Package will appear in your devDependencies.
145 • -O, --save-optional: Package will appear in your optionalDepen‐
147 dencies.
148 • --no-save: Prevents saving to dependencies.
150 When using any of the above options to save dependencies to your pack‐
153 age.json, there are two additional, optional flags:
154 • -E, --save-exact: Saved dependencies will be configured with an
156 exact version rather than using npm's default semver range op‐
157 erator.
158 • -B, --save-bundle: Saved dependencies will also be added to
160 your bundleDependencies list.
161 Further, if you have an npm-shrinkwrap.json or package-lock.json then
164 it 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 npm install sax
177 npm install githubname/reponame
178 npm install @myorg/privatepackage
179 npm install node-tap --save-dev
180 npm install dtrace-provider --save-optional
181 npm install readable-stream --save-exact
182 npm install ansi-regex --save-bundle
183 Note: If there is a file or folder named <name> in the current working
185 directory, then it will try to install that, and only try to fetch the
186 package by name if it is not valid.
187 • npm install <alias>@npm:<name>:
189 Install a package under a custom alias. Allows multiple versions of a
191 same-name package side-by-side, more convenient import names for pack‐
192 ages with otherwise long ones, and using git forks replacements or
193 forked npm packages as replacements. Aliasing works only on your
194 project and does not rename packages in transitive dependencies.
195 Aliases should follow the naming conventions stated in validate-npm-
196 package-name ⟨https://www.npmjs.com/package/validate-npm-package-
197 name#naming-rules⟩.
198 Examples:
200 npm install my-react@npm:react
202 npm install jquery2@npm:jquery@2
203 npm install jquery3@npm:jquery@3
204 npm install npa@npm:npm-package-arg
205 • npm install [<@scope>/]<name>@<tag>:
207 Install the version of the package that is referenced by the specified
209 tag. If the tag does not exist in the registry data for that package,
210 then this will fail.
211 Example:
213 npm install sax@latest
215 npm install @myorg/mypackage@latest
216 • npm install [<@scope>/]<name>@<version>:
218 Install the specified version of the package. This will fail if the
220 version has not been published to the registry.
221 Example:
223 npm install sax@0.1.1
225 npm install @myorg/privatepackage@1.5.0
226 • npm install [<@scope>/]<name>@<version range>:
228 Install a version of the package matching the specified version range.
230 This will follow the same rules for resolving dependencies described in
231 package.json ⟨/configuring-npm/package-json⟩.
232 Note that most version ranges must be put in quotes so that your shell
234 will treat it as a single argument.
235 Example:
237 npm install sax@">=0.1.0 <0.2.0"
239 npm install @myorg/privatepackage@"16 - 17"
240 • npm install <git remote url>:
242 Installs the package from the hosted git provider, cloning it with git.
244 For a full git remote url, only that URL will be attempted.
245 <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
247 <protocol> is one of git, git+ssh, git+http, git+https, or git+file.
249 If #<commit-ish> is provided, it will be used to clone exactly that
251 commit. If the commit-ish has the format #semver:<semver>, <semver> can
252 be any valid semver range or exact version, and npm will look for any
253 tags or refs matching that range in the remote repository, much as it
254 would for a registry dependency. If neither #<commit-ish> or
255 #semver:<semver> is specified, then the default branch of the reposi‐
256 tory is used.
257 If the repository makes use of submodules, those submodules will be
259 cloned as well.
260 If the package being installed contains a prepare script, its dependen‐
262 cies and devDependencies will be installed, and the prepare script will
263 be run, before the package is packaged and installed.
264 The following git environment variables are recognized by npm and will
266 be added to the environment when running git:
267 • GIT_ASKPASS
269 • GIT_EXEC_PATH
271 • GIT_PROXY_COMMAND
273 • GIT_SSH
275 • GIT_SSH_COMMAND
277 • GIT_SSL_CAINFO
279 • GIT_SSL_NO_VERIFY
281 See the git man page for details.
284 Examples:
286 npm install git+ssh://git@github.com:npm/cli.git#v1.0.27
288 npm install git+ssh://git@github.com:npm/cli#pull/273
289 npm install git+ssh://git@github.com:npm/cli#semver:^5.0
290 npm install git+https://isaacs@github.com/npm/cli.git
291 npm install git://github.com/npm/cli.git#v1.0.27
292 GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git
293 • npm install <githubname>/<githubrepo>[#<commit-ish>]:
295 • npm install github:<githubname>/<githubrepo>[#<commit-ish>]:
297 Install the package at https://github.com/githubname/githubrepo by at‐
299 tempting to clone it using git.
300 If #<commit-ish> is provided, it will be used to clone exactly that
302 commit. If the commit-ish has the format #semver:<semver>, <semver> can
303 be any valid semver range or exact version, and npm will look for any
304 tags or refs matching that range in the remote repository, much as it
305 would for a registry dependency. If neither #<commit-ish> or
306 #semver:<semver> is specified, then the default branch is used.
307 As with regular git dependencies, dependencies and devDependencies will
309 be installed if the package has a prepare script before the package is
310 done installing.
311 Examples:
313 npm install mygithubuser/myproject
315 npm install github:mygithubuser/myproject
316 • npm install gist:[<githubname>/]<gistID>[#<commit-
318 ish>|#semver:<semver>]:
319 Install the package at https://gist.github.com/gistID by attempting to
321 clone it using git. The GitHub username associated with the gist is op‐
322 tional and will not be saved in package.json.
323 As with regular git dependencies, dependencies and devDependencies will
325 be installed if the package has a prepare script before the package is
326 done installing.
327 Example:
329 npm install gist:101a11beef
331 • npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-
333 ish>]:
334 Install the package at https://bitbucket.org/bitbucketname/bitbucke‐
336 trepo by attempting to clone it using git.
337 If #<commit-ish> is provided, it will be used to clone exactly that
339 commit. If the commit-ish has the format #semver:<semver>, <semver> can
340 be any valid semver range or exact version, and npm will look for any
341 tags or refs matching that range in the remote repository, much as it
342 would for a registry dependency. If neither #<commit-ish> or
343 #semver:<semver> is specified, then master is used.
344 As with regular git dependencies, dependencies and devDependencies will
346 be installed if the package has a prepare script before the package is
347 done installing.
348 Example:
350 npm install bitbucket:mybitbucketuser/myproject
352 • npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]:
354 Install the package at https://gitlab.com/gitlabname/gitlabrepo by at‐
356 tempting to clone it using git.
357 If #<commit-ish> is provided, it will be used to clone exactly that
359 commit. If the commit-ish has the format #semver:<semver>, <semver> can
360 be any valid semver range or exact version, and npm will look for any
361 tags or refs matching that range in the remote repository, much as it
362 would for a registry dependency. If neither #<commit-ish> or
363 #semver:<semver> is specified, then master is used.
364 As with regular git dependencies, dependencies and devDependencies will
366 be installed if the package has a prepare script before the package is
367 done installing.
368 Example:
370 npm install gitlab:mygitlabuser/myproject
372 npm install gitlab:myusr/myproj#semver:^5.0
373 You may combine multiple arguments and even multiple types of argu‐
376 ments. For example:
377 npm install sax@">=0.1.0 <0.2.0" bench supervisor
379 The --tag argument will apply to all of the specified install targets.
381 If a tag with the given name exists, the tagged version is preferred
382 over newer versions.
383 The --dry-run argument will report in the usual way what the install
385 would have done without actually installing anything.
386 The --package-lock-only argument will only update the package-
388 lock.json, instead of checking node_modules and downloading dependen‐
389 cies.
390 The -f or --force argument will force npm to fetch remote resources
392 even if a local copy exists on disk.
393 npm install sax --force
395 Configuration
397 See the npm help config help doc. Many of the configuration params have
398 some effect on installation, since that's most of what npm does.
399 These are some of the most common options related to installation.
401 save
403 • Default: true unless when using npm update where it defaults to
404 false
405 • Type: Boolean
407 Save installed packages to a package.json file as dependencies.
410 When used with the npm rm command, removes the dependency from pack‐
412 age.json.
413 Will also prevent writing to package-lock.json if set to false.
415 save-exact
417 • Default: false
418 • Type: Boolean
420 Dependencies saved to package.json will be configured with an exact
423 version rather than using npm's default semver range operator.
424 global
426 • Default: false
427 • Type: Boolean
429 Operates in "global" mode, so that packages are installed into the pre‐
432 fix folder instead of the current working directory. See npm help fold‐
433 ers for more on the differences in behavior.
434 • packages are installed into the {prefix}/lib/node_modules folder,
436 instead of the current working directory.
437 • bin files are linked to {prefix}/bin
439 • man pages are linked to {prefix}/share/man
441 install-strategy
444 • Default: "hoisted"
445 • Type: "hoisted", "nested", "shallow", or "linked"
447 Sets the strategy for installing packages in node_modules. hoisted (de‐
450 fault): Install non-duplicated in top-level, and duplicated as neces‐
451 sary within directory structure. nested: (formerly --legacy-bundling)
452 install in place, no hoisting. shallow (formerly --global-style) only
453 install direct deps at top-level. linked: (experimental) install in
454 node_modules/.store, link in place, unhoisted.
455 legacy-bundling
457 • Default: false
458 • Type: Boolean
460 • DEPRECATED: This option has been deprecated in favor of --install-
462 strategy=nested
463 Instead of hoisting package installs in node_modules, install packages
466 in the same manner that they are depended on. This may cause very deep
467 directory structures and duplicate package installs as there is no de-
468 duplicating. Sets --install-strategy=nested.
469 global-style
471 • Default: false
472 • Type: Boolean
474 • DEPRECATED: This option has been deprecated in favor of --install-
476 strategy=shallow
477 Only install direct dependencies in the top level node_modules, but
480 hoist on deeper dependencies. Sets --install-strategy=shallow.
481 omit
483 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
484 duction', otherwise empty.
485 • Type: "dev", "optional", or "peer" (can be set multiple times)
487 Dependency types to omit from the installation tree on disk.
490 Note that these dependencies are still resolved and added to the pack‐
492 age-lock.json or npm-shrinkwrap.json file. They are just not physically
493 installed on disk.
494 If a package type appears in both the --include and --omit lists, then
496 it will be included.
497 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
499 ment variable will be set to 'production' for all lifecycle scripts.
500 include
502 • Default:
503 • Type: "prod", "dev", "optional", or "peer" (can be set multiple
505 times)
506 Option that allows for defining which types of dependencies to install.
509 This is the inverse of --omit=<type>.
511 Dependency types specified in --include will not be omitted, regardless
513 of the order in which omit/include are specified on the command-line.
514 strict-peer-deps
516 • Default: false
517 • Type: Boolean
519 If set to true, and --legacy-peer-deps is not set, then any conflicting
522 peerDependencies will be treated as an install failure, even if npm
523 could reasonably guess the appropriate resolution based on non-peer de‐
524 pendency relationships.
525 By default, conflicting peerDependencies deep in the dependency graph
527 will be resolved using the nearest non-peer dependency specification,
528 even if doing so will result in some packages receiving a peer depen‐
529 dency outside the range set in their package's peerDependencies object.
530 When such an override is performed, a warning is printed, explaining
532 the conflict and the packages involved. If --strict-peer-deps is set,
533 then this warning is treated as a failure.
534 prefer-dedupe
536 • Default: false
537 • Type: Boolean
539 Prefer to deduplicate packages if possible, rather than choosing a
542 newer version of a dependency.
543 package-lock
545 • Default: true
546 • Type: Boolean
548 If set to false, then ignore package-lock.json files when installing.
551 This will also prevent writing package-lock.json if save is true.
552 package-lock-only
554 • Default: false
555 • Type: Boolean
557 If set to true, the current operation will only use the package-
560 lock.json, ignoring node_modules.
561 For update this means only the package-lock.json will be updated, in‐
563 stead of checking node_modules and downloading dependencies.
564 For list this means the output will be based on the tree described by
566 the package-lock.json, rather than the contents of node_modules.
567 foreground-scripts
569 • Default: false
570 • Type: Boolean
572 Run all build scripts (ie, preinstall, install, and postinstall)
575 scripts for installed packages in the foreground process, sharing stan‐
576 dard input, output, and error with the main npm process.
577 Note that this will generally make installs run slower, and be much
579 noisier, but can be useful for debugging.
580 ignore-scripts
582 • Default: false
583 • Type: Boolean
585 If true, npm does not run scripts specified in package.json files.
588 Note that commands explicitly intended to run a particular script, such
590 as npm start, npm stop, npm restart, npm test, and npm run-script will
591 still run their intended script if ignore-scripts is set, but they will
592 not run any pre- or post-scripts.
593 audit
595 • Default: true
596 • Type: Boolean
598 When "true" submit audit reports alongside the current npm command to
601 the default registry and all registries configured for scopes. See the
602 documentation for npm help audit for details on what is submitted.
603 bin-links
605 • Default: true
606 • Type: Boolean
608 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
611 ecutables.
612 Set to false to have it not do this. This can be used to work around
614 the fact that some file systems don't support symlinks, even on osten‐
615 sibly Unix systems.
616 fund
618 • Default: true
619 • Type: Boolean
621 When "true" displays the message at the end of each npm install ac‐
624 knowledging the number of dependencies looking for funding. See npm
625 help fund for details.
626 dry-run
628 • Default: false
629 • Type: Boolean
631 Indicates that you don't want npm to make any changes and that it
634 should only report what it would have done. This can be passed into any
635 of the commands that modify your local installation, eg, install, up‐
636 date, dedupe, uninstall, as well as pack and publish.
637 Note: This is NOT honored by other network related commands, eg dist-
639 tags, owner, etc.
640 cpu
642 • Default: null
643 • Type: null or String
645 Override CPU architecture of native modules to install. Acceptable val‐
648 ues are same as cpu field of package.json, which comes from
649 process.arch.
650 os
652 • Default: null
653 • Type: null or String
655 Override OS of native modules to install. Acceptable values are same as
658 os field of package.json, which comes from process.platform.
659 workspace
661 • Default:
662 • Type: String (can be set multiple times)
664 Enable running a command in the context of the configured workspaces of
667 the current project while filtering by running only the workspaces de‐
668 fined by this configuration option.
669 Valid values for the workspace config are either:
671 • Workspace names
673 • Path to a workspace directory
675 • Path to a parent workspace directory (will result in selecting all
677 workspaces within that folder)
678 When set for the npm init command, this may be set to the folder of a
681 workspace which does not yet exist, to create the folder and set it up
682 as a brand new workspace within the project.
683 This value is not exported to the environment for child processes.
685 workspaces
687 • Default: null
688 • Type: null or Boolean
690 Set to true to run the command in the context of all configured
693 workspaces.
694 Explicitly setting this to false will cause commands like install to
696 ignore workspaces altogether. When not set explicitly:
697 • Commands that operate on the node_modules tree (install, update,
699 etc.) will link workspaces into the node_modules folder. - Commands
700 that do other things (test, exec, publish, etc.) will operate on
701 the root project, unless one or more workspaces are specified in
702 the workspace config.
703 This value is not exported to the environment for child processes.
706 include-workspace-root
708 • Default: false
709 • Type: Boolean
711 Include the workspace root when workspaces are enabled for a command.
714 When false, specifying individual workspaces via the workspace config,
716 or all workspaces via the workspaces flag, will cause npm to operate
717 only on the specified workspaces, and not on the root project.
718 This value is not exported to the environment for child processes.
720 install-links
722 • Default: false
723 • Type: Boolean
725 When set file: protocol dependencies will be packed and installed as
728 regular dependencies instead of creating a symlink. This option has no
729 effect on workspaces.
730 Algorithm
732 Given a package{dep} structure: A{B,C}, B{C}, C{D}, the npm install al‐
733 gorithm produces:
734 A
736 +-- B
737 +-- C
738 +-- D
739 That is, the dependency from B to C is satisfied by the fact that A al‐
741 ready caused C to be installed at a higher level. D is still installed
742 at the top level because nothing conflicts with it.
743 For A{B,C}, B{C,D@1}, C{D@2}, this algorithm produces:
745 A
747 +-- B
748 +-- C
749 `-- D@2
750 +-- D@1
751 Because B's D@1 will be installed in the top-level, C now has to in‐
753 stall D@2 privately for itself. This algorithm is deterministic, but
754 different trees may be produced if two dependencies are requested for
755 installation in a different order.
756 See npm help folders for a more detailed description of the specific
758 folder structures that npm creates.
759 See Also
761 • npm help folders
762 • npm help update
764 • npm help audit
766 • npm help fund
768 • npm help link
770 • npm help rebuild
772 • npm help scripts
774 • npm help config
776 • npm help npmrc
778 • npm help registry
780 • npm help dist-tag
782 • npm help uninstall
784 • npm help shrinkwrap
786 • package.json ⟨/configuring-npm/package-json⟩
788 • npm help workspaces
790 November 2023 NPM-INSTALL(1)