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 npm help package-lock.json and npm help shrinkwrap.
27 A package is:
29 • a) a folder containing a program described by a npm help package.json
31 file
32 • b) a gzipped tarball containing (a)
34 • c) a url that resolves to (b)
36 • d) a <name>@<version> that is published on the registry (see npm help
38 registry) with (c)
39 • e) a <name>@<tag> (see npm help dist-tag) that points to (d)
41 • f) a <name> that has a "latest" tag satisfying (e)
43 • g) a <git remote url> that resolves to (a)
45 Even if you never publish your package, you can still get a lot of ben‐
48 efits of using npm if you just want to write a node program (a), and
49 perhaps if you also want to be able to easily install it elsewhere af‐
50 ter packing it up into a tarball (b).
51 • npm install (in a package directory, no arguments):
53 Install the dependencies to the local node_modules folder.
54 In global mode (ie, with -g or --global appended to the command),
55 it installs the current package context (ie, the current working
56 directory) as a global package.
57 By default, npm install will install all modules listed as
58 dependencies in npm help package.json.
59 With the --production flag (or when the NODE_ENV environment
60 variable is set to production), npm will not install modules listed
61 in devDependencies. To install all modules listed in both
62 dependencies and devDependencies when NODE_ENV environment
63 variable is set to production, you can use --production=false.
64 NOTE: The --production flag has no particular meaning when adding a
65 dependency to a project.
66 • npm install <folder>:
69 If <folder> sits inside the root of your project, its dependencies
70 will be installed and may
71 be hoisted to the top-level node_modules as they would for other
72 types of dependencies. If <folder> sits outside the root of your
73 project,
74 npm will not install the package dependencies in the directory
75 <folder>,
76 but it will create a symlink to <folder>. NOTE: If you want to in‐
77 stall the content of a directory like a package from the registry in‐
78 stead of creating a link, you would need to use the --install-links
79 option.
80 Example:
82 npm install ../../other-package --install-links
84 npm install ./sub-package
85 • 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 • The filename must use .tar, .tar.gz, or .tgz as the extension.
95 • 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 • The package must contain a package.json file with name and version
102 properties. Example:
103 npm install ./package.tgz
105 • 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 npm install https://github.com/indexzero/forever/tarball/v0.5.6
115 • 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 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 • -P, --save-prod: Package will appear in your dependencies.
131 This is the default unless -D or -O are present.
132 • -D, --save-dev: Package will appear in your devDependencies.
134 • -O, --save-optional: Package will appear in your optionalDe‐
136 pendencies.
137 • --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 • -E, --save-exact: Saved dependencies will be configured with
143 an exact version rather than using npm's default semver range
144 operator.
145 • -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 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 • 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 • 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 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 • 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 npm install sax@latest
195 npm install @myorg/mypackage@latest
196 • 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 npm install sax@0.1.1
204 npm install @myorg/privatepackage@1.5.0
205 • 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 npm install sax@">=0.1.0 <0.2.0"
218 npm install @myorg/privatepackage@"16 - 17"
219 • 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 <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 • GIT_ASKPASS
245 • GIT_EXEC_PATH
247 • GIT_PROXY_COMMAND
249 • GIT_SSH
251 • GIT_SSH_COMMAND
253 • GIT_SSL_CAINFO
255 • GIT_SSL_NO_VERIFY See the git man page for details. Examples:
257 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 • npm install <githubname>/<githubrepo>[#<commit-ish>]:
267 • 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 the default branch 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 npm install mygithubuser/myproject
285 npm install github:mygithubuser/myproject
286 • 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 npm install gist:101a11beef
301 • 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 npm install bitbucket:mybitbucketuser/myproject
324 • 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 npm install gitlab:mygitlabuser/myproject
346 npm install gitlab:myusr/myproj#semver:^5.0
347 You may combine multiple arguments and even multiple types of argu‐
350 ments. For example:
351 npm install sax@">=0.1.0 <0.2.0" bench supervisor
353 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 The --dry-run argument will report in the usual way what the install
359 would have done without actually installing anything.
360 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 The -f or --force argument will force npm to fetch remote resources
366 even if a local copy exists on disk.
367 npm install sax --force
369 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 These are some of the most common options related to installation.
375 save
377 • Default: true unless when using npm update where it defaults to false
378 • Type: Boolean
380 Save installed packages to a package.json file as dependencies.
383 When used with the npm rm command, removes the dependency from pack‐
385 age.json.
386 Will also prevent writing to package-lock.json if set to false.
388 save-exact
390 • Default: false
391 • Type: Boolean
393 Dependencies saved to package.json will be configured with an exact
396 version rather than using npm's default semver range operator.
397 global
399 • Default: false
400 • Type: Boolean
402 Operates in "global" mode, so that packages are installed into the pre‐
405 fix folder instead of the current working directory. See npm help fold‐
406 ers for more on the differences in behavior.
407 • packages are installed into the {prefix}/lib/node_modules folder, in‐
409 stead of the current working directory.
410 • bin files are linked to {prefix}/bin
412 • man pages are linked to {prefix}/share/man
414 global-style
417 • Default: false
418 • Type: Boolean
420 Causes npm to install the package into your local node_modules folder
423 with the same layout it uses with the global node_modules folder. Only
424 your direct dependencies will show in node_modules and everything they
425 depend on will be flattened in their node_modules folders. This obvi‐
426 ously will eliminate some deduping. If used with legacy-bundling,
427 legacy-bundling will be preferred.
428 legacy-bundling
430 • Default: false
431 • Type: Boolean
433 Causes npm to install the package such that versions of npm prior to
436 1.4, such as the one included with node 0.8, can install the package.
437 This eliminates all automatic deduping. If used with global-style this
438 option will be preferred.
439 omit
441 • Default: 'dev' if the NODE_ENV environment variable is set to 'pro‐
442 duction', otherwise empty.
443 • Type: "dev", "optional", or "peer" (can be set multiple times)
445 Dependency types to omit from the installation tree on disk.
448 Note that these dependencies are still resolved and added to the pack‐
450 age-lock.json or npm-shrinkwrap.json file. They are just not physically
451 installed on disk.
452 If a package type appears in both the --include and --omit lists, then
454 it will be included.
455 If the resulting omit list includes 'dev', then the NODE_ENV environ‐
457 ment variable will be set to 'production' for all lifecycle scripts.
458 strict-peer-deps
460 • Default: false
461 • Type: Boolean
463 If set to true, and --legacy-peer-deps is not set, then any conflicting
466 peerDependencies will be treated as an install failure, even if npm
467 could reasonably guess the appropriate resolution based on non-peer de‐
468 pendency relationships.
469 By default, conflicting peerDependencies deep in the dependency graph
471 will be resolved using the nearest non-peer dependency specification,
472 even if doing so will result in some packages receiving a peer depen‐
473 dency outside the range set in their package's peerDependencies object.
474 When such and override is performed, a warning is printed, explaining
476 the conflict and the packages involved. If --strict-peer-deps is set,
477 then this warning is treated as a failure.
478 package-lock
480 • Default: true
481 • Type: Boolean
483 If set to false, then ignore package-lock.json files when installing.
486 This will also prevent writing package-lock.json if save is true.
487 This configuration does not affect npm ci.
489 foreground-scripts
491 • Default: false
492 • Type: Boolean
494 Run all build scripts (ie, preinstall, install, and postinstall)
497 scripts for installed packages in the foreground process, sharing stan‐
498 dard input, output, and error with the main npm process.
499 Note that this will generally make installs run slower, and be much
501 noisier, but can be useful for debugging.
502 ignore-scripts
504 • Default: false
505 • Type: Boolean
507 If true, npm does not run scripts specified in package.json files.
510 Note that commands explicitly intended to run a particular script, such
512 as npm start, npm stop, npm restart, npm test, and npm run-script will
513 still run their intended script if ignore-scripts is set, but they will
514 not run any pre- or post-scripts.
515 audit
517 • Default: true
518 • Type: Boolean
520 When "true" submit audit reports alongside the current npm command to
523 the default registry and all registries configured for scopes. See the
524 documentation for npm help audit for details on what is submitted.
525 bin-links
527 • Default: true
528 • Type: Boolean
530 Tells npm to create symlinks (or .cmd shims on Windows) for package ex‐
533 ecutables.
534 Set to false to have it not do this. This can be used to work around
536 the fact that some file systems don't support symlinks, even on osten‐
537 sibly Unix systems.
538 fund
540 • Default: true
541 • Type: Boolean
543 When "true" displays the message at the end of each npm install ac‐
546 knowledging the number of dependencies looking for funding. See npm
547 help npm fund for details.
548 dry-run
550 • Default: false
551 • Type: Boolean
553 Indicates that you don't want npm to make any changes and that it
556 should only report what it would have done. This can be passed into any
557 of the commands that modify your local installation, eg, install, up‐
558 date, dedupe, uninstall, as well as pack and publish.
559 Note: This is NOT honored by other network related commands, eg
561 dist-tags, owner, etc.
562 workspace
564 • Default:
565 • Type: String (can be set multiple times)
567 Enable running a command in the context of the configured workspaces of
570 the current project while filtering by running only the workspaces de‐
571 fined by this configuration option.
572 Valid values for the workspace config are either:
574 • Workspace names
576 • Path to a workspace directory
578 • Path to a parent workspace directory (will result in selecting all
580 workspaces within that folder)
581 When set for the npm init command, this may be set to the folder of a
584 workspace which does not yet exist, to create the folder and set it up
585 as a brand new workspace within the project.
586 This value is not exported to the environment for child processes.
588 workspaces
590 • Default: null
591 • Type: null or Boolean
593 Set to true to run the command in the context of all configured
596 workspaces.
597 Explicitly setting this to false will cause commands like install to
599 ignore workspaces altogether. When not set explicitly:
600 • Commands that operate on the node_modules tree (install, update,
602 etc.) will link workspaces into the node_modules folder. - Commands
603 that do other things (test, exec, publish, etc.) will operate on the
604 root project, unless one or more workspaces are specified in the
605 workspace config.
606 This value is not exported to the environment for child processes.
609 include-workspace-root
611 • Default: false
612 • Type: Boolean
614 Include the workspace root when workspaces are enabled for a command.
617 When false, specifying individual workspaces via the workspace config,
619 or all workspaces via the workspaces flag, will cause npm to operate
620 only on the specified workspaces, and not on the root project.
621 This value is not exported to the environment for child processes.
623 install-links
625 • Default: false
626 • Type: Boolean
628 When set file: protocol dependencies that exist outside of the project
631 root will be packed and installed as regular dependencies instead of
632 creating a symlink. This option has no effect on workspaces.
633 Algorithm
635 Given a package{dep} structure: A{B,C}, B{C}, C{D}, the npm install al‐
636 gorithm produces:
637 A
639 +-- B
640 +-- C
641 +-- D
642 That is, the dependency from B to C is satisfied by the fact that A al‐
644 ready caused C to be installed at a higher level. D is still installed
645 at the top level because nothing conflicts with it.
646 For A{B,C}, B{C,D@1}, C{D@2}, this algorithm produces:
648 A
650 +-- B
651 +-- C
652 `-- D@2
653 +-- D@1
654 Because B's D@1 will be installed in the top-level, C now has to in‐
656 stall D@2 privately for itself. This algorithm is deterministic, but
657 different trees may be produced if two dependencies are requested for
658 installation in a different order.
659 See npm help folders for a more detailed description of the specific
661 folder structures that npm creates.
662 See Also
664 • npm help folders
665 • npm help update
667 • npm help audit
669 • npm help fund
671 • npm help link
673 • npm help rebuild
675 • npm help scripts
677 • npm help config
679 • npm help npmrc
681 • npm help registry
683 • npm help dist-tag
685 • npm help uninstall
687 • npm help shrinkwrap
689 • npm help package.json
691 • npm help workspaces
693 September 2022 NPM-INSTALL(1)