<!doctype html>
< html >
< title > npm-install< / title >
< meta http-equiv = "content-type" value = "text/html;utf-8" >
< link rel = "stylesheet" type = "text/css" href = "../../static/style.css" >
< link rel = "canonical" href = "https://www.npmjs.org/doc/cli/npm-install.html" >
< script async = true src = "../../static/toc.js" > < / script >
< body >
< div id = "wrapper" >
< h1 > < a href = "../cli/npm-install.html" > npm-install< / a > < / h1 > < p > Install a package< / p >
< h2 id = "synopsis" > SYNOPSIS< / h2 >
< pre > < code > npm install (with no args in a package dir)
npm install < tarball file>
npm install < tarball url>
npm install < folder>
npm install [@< scope> /]< name> [--save|--save-dev|--save-optional] [--save-exact]
npm install [@< scope> /]< name> @< tag>
npm install [@< scope> /]< name> @< version>
npm install [@< scope> /]< name> @< version range>
npm i (with any of the previous argument usage)
< / code > < / pre > < h2 id = "description" > DESCRIPTION< / h2 >
< p > This command installs a package, and any packages that it depends on. If the
package has a shrinkwrap file, the installation of dependencies will be driven
by that. See < a href = "../cli/npm-shrinkwrap.html" > < a href = "../cli/npm-shrinkwrap.html" > npm-shrinkwrap(1)< / a > < / a > .< / p >
< p > A < code > package< / code > is:< / p >
< ul >
< li > a) a folder containing a program described by a package.json file< / li >
< li > b) a gzipped tarball containing (a)< / li >
< li > c) a url that resolves to (b)< / li >
< li > d) a < code > < name> @< version> < / code > that is published on the registry (see < code > < a href = "../misc/npm-registry.html" > < a href = "../misc/npm-registry.html" > npm-registry(7)< / a > < / a > < / code > ) with (c)< / li >
< li > e) a < code > < name> @< tag> < / code > that points to (d)< / li >
< li > f) a < code > < name> < / code > that has a " latest" tag satisfying (e)< / li >
< li > g) a < code > < git remote url> < / code > that resolves to (b)< / li >
< / ul >
< p > Even if you never publish your package, you can still get a lot of
benefits of using npm if you just want to write a node program (a), and
perhaps if you also want to be able to easily install it elsewhere
after packing it up into a tarball (b).< / p >
< ul >
< li > < p > < code > npm install< / code > (in package directory, no arguments):< / p >
< p > Install the dependencies in the local node_modules folder.< / p >
< p > In global mode (ie, with < code > -g< / code > or < code > --global< / code > appended to the command),
it installs the current package context (ie, the current working
directory) as a global package.< / p >
< p > By default, < code > npm install< / code > will install all modules listed as
dependencies. With the < code > --production< / code > flag,
npm will not install modules listed in < code > devDependencies< / code > .< / p >
< / li >
< li > < p > < code > npm install < folder> < / code > :< / p >
< p > Install a package that is sitting in a folder on the filesystem.< / p >
< / li >
< li > < p > < code > npm install < tarball file> < / code > :< / p >
< p > Install a package that is sitting on the filesystem. Note: if you just want
to link a dev directory into your npm root, you can do this more easily by
using < code > npm link< / code > .< / p >
< p > Example:< / p >
< pre > < code > npm install ./package.tgz
< / code > < / pre > < / li >
< li > < p > < code > npm install < tarball url> < / code > :< / p >
< p > Fetch the tarball url, and then install it. In order to distinguish between
this and other options, the argument must start with " http://" or " https://" < / p >
< p > Example:< / p >
< pre > < code > npm install https://github.com/indexzero/forever/tarball/v0.5.6
< / code > < / pre > < / li >
< li > < p > < code > npm install [@< scope> /]< name> [--save|--save-dev|--save-optional]< / code > :< / p >
< p > Do a < code > < name> @< tag> < / code > install, where < code > < tag> < / code > is the " tag" config. (See
< code > < a href = "../misc/npm-config.html" > < a href = "../misc/npm-config.html" > npm-config(7)< / a > < / a > < / code > .)< / p >
< p > In most cases, this will install the latest version
of the module published on npm.< / p >
< p > Example:< / p >
< pre > < code > npm install sax
< / code > < / pre > < p > < code > npm install< / code > takes 3 exclusive, optional flags which save or update
the package version in your main package.json:< / p >
< ul >
< li > < p > < code > --save< / code > : Package will appear in your < code > dependencies< / code > .< / p >
< / li >
< li > < p > < code > --save-dev< / code > : Package will appear in your < code > devDependencies< / code > .< / p >
< / li >
< li > < p > < code > --save-optional< / code > : Package will appear in your < code > optionalDependencies< / code > .< / p >
< p > When using any of the above options to save dependencies to your
package.json, there is an additional, optional flag:< / p >
< / li >
< li > < p > < code > --save-exact< / code > : Saved dependencies will be configured with an
exact version rather than using npm' s default semver range
operator.< / p >
< p > < code > < scope> < / code > is optional. The package will be downloaded from the registry
associated with the specified scope. If no registry is associated with
the given scope the default registry is assumed. See < code > < a href = "../misc/npm-scope.html" > < a href = "../misc/npm-scope.html" > npm-scope(7)< / a > < / a > < / code > .< / p >
< p > Note: if you do not include the @-symbol on your scope name, npm will
interpret this as a GitHub repository instead, see below. Scopes names
must also be followed by a slash.< / p >
< p > Examples:< / p >
< pre > < code > npm install sax --save
npm install githubname/reponame
npm install @myorg/privatepackage
npm install node-tap --save-dev
npm install dtrace-provider --save-optional
npm install readable-stream --save --save-exact
< / code > < / pre > < / li >
< / ul >
< / li >
< / ul >
< pre > < code > **Note**: If there is a file or folder named `< name> ` in the current
working directory, then it will try to install that, and only try to
fetch the package by name if it is not valid.
< / code > < / pre > < ul >
< li > < p > < code > npm install [@< scope> /]< name> @< tag> < / code > :< / p >
< p > Install the version of the package that is referenced by the specified tag.
If the tag does not exist in the registry data for that package, then this
will fail.< / p >
< p > Example:< / p >
< pre > < code > npm install sax@latest
npm install @myorg/mypackage@latest
< / code > < / pre > < / li >
< li > < p > < code > npm install [@< scope> /]< name> @< version> < / code > :< / p >
< p > Install the specified version of the package. This will fail if the
version has not been published to the registry.< / p >
< p > Example:< / p >
< pre > < code > npm install sax@0.1.1
npm install @myorg/privatepackage@1.5.0
< / code > < / pre > < / li >
< li > < p > < code > npm install [@< scope> /]< name> @< version range> < / code > :< / p >
< p > Install a version of the package matching the specified version range. This
will follow the same rules for resolving dependencies described in < code > < a href = "../files/package.json.html" > < a href = "../files/package.json.html" > package.json(5)< / a > < / a > < / code > .< / p >
< p > Note that most version ranges must be put in quotes so that your shell will
treat it as a single argument.< / p >
< p > Example:< / p >
< pre > < code > npm install sax@" > =0.1.0 < 0.2.0"
npm install @myorg/privatepackage@" > =0.1.0 < 0.2.0"
< / code > < / pre > < / li >
< li > < p > < code > npm install < githubname> /< githubrepo> < / code > :< / p >
< p > Install the package at < code > https://github.com/githubname/githubrepo" by
attempting to clone it using< / code > git`.< / p >
< p > Example:< / p >
< pre > < code > npm install mygithubuser/myproject
< / code > < / pre > < p > To reference a package in a git repo that is not on GitHub, see git
remote urls below.< / p >
< / li >
< li > < p > < code > npm install < git remote url> < / code > :< / p >
< p > Install a package by cloning a git remote url. The format of the git
url is:< / p >
< pre > < code > < protocol> ://[< user> @]< hostname> < separator> < path> [#< commit-ish> ]
< / code > < / pre > < p > < code > < protocol> < / code > is one of < code > git< / code > , < code > git+ssh< / code > , < code > git+http< / code > , or
< code > git+https< / code > . If no < code > < commit-ish> < / code > is specified, then < code > master< / code > is
used.< / p >
< p > Examples:< / p >
< pre > < code > git+ssh://git@github.com:npm/npm.git#v1.0.27
git+https://isaacs@github.com/npm/npm.git
git://github.com/npm/npm.git#v1.0.27
< / code > < / pre > < / li >
< / ul >
< p > You may combine multiple arguments, and even multiple types of arguments.
For example:< / p >
< pre > < code > npm install sax@" > =0.1.0 < 0.2.0" bench supervisor
< / code > < / pre > < p > The < code > --tag< / code > argument will apply to all of the specified install targets. If a
tag with the given name exists, the tagged version is preferred over newer
versions.< / p >
< p > The < code > --force< / code > argument will force npm to fetch remote resources even if a
local copy exists on disk.< / p >
< pre > < code > npm install sax --force
< / code > < / pre > < p > The < code > --global< / code > argument will cause npm to install the package globally
rather than locally. See < code > < a href = "../files/npm-folders.html" > < a href = "../files/npm-folders.html" > npm-folders(5)< / a > < / a > < / code > .< / p >
< p > The < code > --link< / code > argument will cause npm to link global installs into the
local space in some cases.< / p >
< p > The < code > --no-bin-links< / code > argument will prevent npm from creating symlinks for
any binaries the package might contain.< / p >
< p > The < code > --no-optional< / code > argument will prevent optional dependencies from
being installed.< / p >
< p > The < code > --no-shrinkwrap< / code > argument, which will ignore an available
shrinkwrap file and use the package.json instead.< / p >
< p > The < code > --nodedir=/path/to/node/source< / code > argument will allow npm to find the
node source code so that npm can compile native modules.< / p >
< p > See < code > < a href = "../misc/npm-config.html" > < a href = "../misc/npm-config.html" > npm-config(7)< / a > < / a > < / code > . Many of the configuration params have some
effect on installation, since that' s most of what npm does.< / p >
< h2 id = "algorithm" > ALGORITHM< / h2 >
< p > To install a package, npm uses the following algorithm:< / p >
< pre > < code > install(where, what, family, ancestors)
fetch what, unpack to < where> /node_modules/< what>
for each dep in what.dependencies
resolve dep to precise version
for each dep@version in what.dependencies
not in < where> /node_modules/< what> /node_modules/*
and not in < family>
add precise version deps to < family>
install(< where> /node_modules/< what> , dep, family)
< / code > < / pre > < p > For this < code > package{dep}< / code > structure: < code > A{B,C}, B{C}, C{D}< / code > ,
this algorithm produces:< / p >
< pre > < code > A
+-- B
`-- C
`-- D
< / code > < / pre > < p > That is, the dependency from B to C is satisfied by the fact that A
already caused C to be installed at a higher level.< / p >
< p > See < a href = "../files/npm-folders.html" > < a href = "../files/npm-folders.html" > npm-folders(5)< / a > < / a > for a more detailed description of the specific
folder structures that npm creates.< / p >
< h3 id = "limitations-of-npm-s-install-algorithm" > Limitations of npm' s Install Algorithm< / h3 >
< p > There are some very rare and pathological edge-cases where a cycle can
cause npm to try to install a never-ending tree of packages. Here is
the simplest case:< / p >
< pre > < code > A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...
< / code > < / pre > < p > where < code > A< / code > is some version of a package, and < code > A' < / code > is a different version
of the same package. Because < code > B< / code > depends on a different version of < code > A< / code >
than the one that is already in the tree, it must install a separate
copy. The same is true of < code > A' < / code > , which must install < code > B' < / code > . Because < code > B' < / code >
depends on the original version of < code > A< / code > , which has been overridden, the
cycle falls into infinite regress.< / p >
< p > To avoid this situation, npm flat-out refuses to install any
< code > name@version< / code > that is already present anywhere in the tree of package
folder ancestors. A more correct, but more complex, solution would be
to symlink the existing version into the new location. If this ever
affects a real use-case, it will be investigated.< / p >
< h2 id = "see-also" > SEE ALSO< / h2 >
< ul >
< li > < a href = "../files/npm-folders.html" > < a href = "../files/npm-folders.html" > npm-folders(5)< / a > < / a > < / li >
< li > < a href = "../cli/npm-update.html" > < a href = "../cli/npm-update.html" > npm-update(1)< / a > < / a > < / li >
< li > < a href = "../cli/npm-link.html" > < a href = "../cli/npm-link.html" > npm-link(1)< / a > < / a > < / li >
< li > < a href = "../cli/npm-rebuild.html" > < a href = "../cli/npm-rebuild.html" > npm-rebuild(1)< / a > < / a > < / li >
< li > < a href = "../misc/npm-scripts.html" > < a href = "../misc/npm-scripts.html" > npm-scripts(7)< / a > < / a > < / li >
< li > < a href = "../cli/npm-build.html" > < a href = "../cli/npm-build.html" > npm-build(1)< / a > < / a > < / li >
< li > < a href = "../cli/npm-config.html" > < a href = "../cli/npm-config.html" > npm-config(1)< / a > < / a > < / li >
< li > < a href = "../misc/npm-config.html" > < a href = "../misc/npm-config.html" > npm-config(7)< / a > < / a > < / li >
< li > < a href = "../files/npmrc.html" > < a href = "../files/npmrc.html" > npmrc(5)< / a > < / a > < / li >
< li > < a href = "../misc/npm-registry.html" > < a href = "../misc/npm-registry.html" > npm-registry(7)< / a > < / a > < / li >
< li > < a href = "../cli/npm-tag.html" > < a href = "../cli/npm-tag.html" > npm-tag(1)< / a > < / a > < / li >
< li > < a href = "../cli/npm-rm.html" > < a href = "../cli/npm-rm.html" > npm-rm(1)< / a > < / a > < / li >
< li > < a href = "../cli/npm-shrinkwrap.html" > < a href = "../cli/npm-shrinkwrap.html" > npm-shrinkwrap(1)< / a > < / a > < / li >
< / ul >
< / div >
< table border = 0 cellspacing = 0 cellpadding = 0 id = npmlogo >
< tr > < td style = "width:180px;height:10px;background:rgb(237,127,127)" colspan = 18 > < / td > < / tr >
< tr > < td rowspan = 4 style = "width:10px;height:10px;background:rgb(237,127,127)" > < / td > < td style = "width:40px;height:10px;background:#fff" colspan = 4 > < / td > < td style = "width:10px;height:10px;background:rgb(237,127,127)" rowspan = 4 > < / td > < td style = "width:40px;height:10px;background:#fff" colspan = 4 > < / td > < td rowspan = 4 style = "width:10px;height:10px;background:rgb(237,127,127)" > < / td > < td colspan = 6 style = "width:60px;height:10px;background:#fff" > < / td > < td style = "width:10px;height:10px;background:rgb(237,127,127)" rowspan = 4 > < / td > < / tr >
< tr > < td colspan = 2 style = "width:20px;height:30px;background:#fff" rowspan = 3 > < / td > < td style = "width:10px;height:10px;background:rgb(237,127,127)" rowspan = 3 > < / td > < td style = "width:10px;height:10px;background:#fff" rowspan = 3 > < / td > < td style = "width:20px;height:10px;background:#fff" rowspan = 4 colspan = 2 > < / td > < td style = "width:10px;height:20px;background:rgb(237,127,127)" rowspan = 2 > < / td > < td style = "width:10px;height:10px;background:#fff" rowspan = 3 > < / td > < td style = "width:20px;height:10px;background:#fff" rowspan = 3 colspan = 2 > < / td > < td style = "width:10px;height:10px;background:rgb(237,127,127)" rowspan = 3 > < / td > < td style = "width:10px;height:10px;background:#fff" rowspan = 3 > < / td > < td style = "width:10px;height:10px;background:rgb(237,127,127)" rowspan = 3 > < / td > < / tr >
< tr > < td style = "width:10px;height:10px;background:#fff" rowspan = 2 > < / td > < / tr >
< tr > < td style = "width:10px;height:10px;background:#fff" > < / td > < / tr >
< tr > < td style = "width:60px;height:10px;background:rgb(237,127,127)" colspan = 6 > < / td > < td colspan = 10 style = "width:10px;height:10px;background:rgb(237,127,127)" > < / td > < / tr >
< tr > < td colspan = 5 style = "width:50px;height:10px;background:#fff" > < / td > < td style = "width:40px;height:10px;background:rgb(237,127,127)" colspan = 4 > < / td > < td style = "width:90px;height:10px;background:#fff" colspan = 9 > < / td > < / tr >
< / table >
< p id = "footer" > npm-install — npm@2.1.6< / p >
