mirror of https://github.com/lukechilds/node.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
351 lines
10 KiB
351 lines
10 KiB
.TH "NPM\-INSTALL" "1" "October 2014" "" ""
|
|
.SH "NAME"
|
|
\fBnpm-install\fR \- Install a package
|
|
.SH SYNOPSIS
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
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)
|
|
.fi
|
|
.RE
|
|
.SH DESCRIPTION
|
|
.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 npm help shrinkwrap\.
|
|
.P
|
|
A \fBpackage\fR is:
|
|
.RS 0
|
|
.IP \(bu 2
|
|
a) a folder containing a program described by a package\.json file
|
|
.IP \(bu 2
|
|
b) a gzipped tarball containing (a)
|
|
.IP \(bu 2
|
|
c) a url that resolves to (b)
|
|
.IP \(bu 2
|
|
d) a \fB<name>@<version>\fR that is published on the registry (see npm help 7 \fBnpm\-registry\fR) with (c)
|
|
.IP \(bu 2
|
|
e) a \fB<name>@<tag>\fR that points to (d)
|
|
.IP \(bu 2
|
|
f) a \fB<name>\fR that has a "latest" tag satisfying (e)
|
|
.IP \(bu 2
|
|
g) a \fB<git remote url>\fR that resolves to (b)
|
|
|
|
.RE
|
|
.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)\.
|
|
.RS 0
|
|
.IP \(bu 2
|
|
\fBnpm install\fR (in package directory, no arguments):
|
|
Install the dependencies in the local node_modules folder\.
|
|
In global mode (ie, with \fB\-g\fR or \fB\-\-global\fR appended to the command),
|
|
it installs the current package context (ie, the current working
|
|
directory) as a global package\.
|
|
By default, \fBnpm install\fR will install all modules listed as
|
|
dependencies\. With the \fB\-\-production\fR flag,
|
|
npm will not install modules listed in \fBdevDependencies\fR\|\.
|
|
.IP \(bu 2
|
|
\fBnpm install <folder>\fR:
|
|
Install a package that is sitting in a folder on the filesystem\.
|
|
.IP \(bu 2
|
|
\fBnpm install <tarball file>\fR:
|
|
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 \fBnpm link\fR\|\.
|
|
Example:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install \./package\.tgz
|
|
.fi
|
|
.RE
|
|
.IP \(bu 2
|
|
\fBnpm install <tarball url>\fR:
|
|
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://"
|
|
Example:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install https://github\.com/indexzero/forever/tarball/v0\.5\.6
|
|
.fi
|
|
.RE
|
|
.IP \(bu 2
|
|
\fBnpm install [@<scope>/]<name> [\-\-save|\-\-save\-dev|\-\-save\-optional]\fR:
|
|
Do a \fB<name>@<tag>\fR install, where \fB<tag>\fR is the "tag" config\. (See
|
|
npm help 7 \fBnpm\-config\fR\|\.)
|
|
In most cases, this will install the latest version
|
|
of the module published on npm\.
|
|
Example:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install sax
|
|
.fi
|
|
.RE
|
|
\fBnpm install\fR takes 3 exclusive, optional flags which save or update
|
|
the package version in your main package\.json:
|
|
.RS 0
|
|
.IP \(bu 2
|
|
\fB\-\-save\fR: Package will appear in your \fBdependencies\fR\|\.
|
|
.IP \(bu 2
|
|
\fB\-\-save\-dev\fR: Package will appear in your \fBdevDependencies\fR\|\.
|
|
.IP \(bu 2
|
|
\fB\-\-save\-optional\fR: Package will appear in your \fBoptionalDependencies\fR\|\.
|
|
When using any of the above options to save dependencies to your
|
|
package\.json, there is an additional, optional flag:
|
|
.IP \(bu 2
|
|
\fB\-\-save\-exact\fR: Saved dependencies will be configured with an
|
|
exact version rather than using npm's default semver range
|
|
operator\.
|
|
\fB<scope>\fR 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 npm help 7 \fBnpm\-scope\fR\|\.
|
|
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\.
|
|
Examples:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
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
|
|
.fi
|
|
.RE
|
|
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
**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\.
|
|
.fi
|
|
.RE
|
|
.RS 0
|
|
.IP \(bu 2
|
|
\fBnpm install [@<scope>/]<name>@<tag>\fR:
|
|
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\.
|
|
Example:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install sax@latest
|
|
npm install @myorg/mypackage@latest
|
|
.fi
|
|
.RE
|
|
.IP \(bu 2
|
|
\fBnpm install [@<scope>/]<name>@<version>\fR:
|
|
Install the specified version of the package\. This will fail if the
|
|
version has not been published to the registry\.
|
|
Example:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install sax@0\.1\.1
|
|
npm install @myorg/privatepackage@1\.5\.0
|
|
.fi
|
|
.RE
|
|
.IP \(bu 2
|
|
\fBnpm install [@<scope>/]<name>@<version range>\fR:
|
|
Install a version of the package matching the specified version range\. This
|
|
will follow the same rules for resolving dependencies described in npm help 5 \fBpackage\.json\fR\|\.
|
|
Note that most version ranges must be put in quotes so that your shell will
|
|
treat it as a single argument\.
|
|
Example:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install sax@">=0\.1\.0 <0\.2\.0"
|
|
npm install @myorg/privatepackage@">=0\.1\.0 <0\.2\.0"
|
|
.fi
|
|
.RE
|
|
.IP \(bu 2
|
|
\fBnpm install <githubname>/<githubrepo>\fR:
|
|
Install the package at \fBhttps://github\.com/githubname/githubrepo" by
|
|
attempting to clone it using\fRgit`\.
|
|
Example:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install mygithubuser/myproject
|
|
.fi
|
|
.RE
|
|
To reference a package in a git repo that is not on GitHub, see git
|
|
remote urls below\.
|
|
.IP \(bu 2
|
|
\fBnpm install <git remote url>\fR:
|
|
Install a package by cloning a git remote url\. The format of the git
|
|
url is:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
<protocol>://[<user>@]<hostname><separator><path>[#<commit\-ish>]
|
|
.fi
|
|
.RE
|
|
\fB<protocol>\fR is one of \fBgit\fR, \fBgit+ssh\fR, \fBgit+http\fR, or
|
|
\fBgit+https\fR\|\. If no \fB<commit\-ish>\fR is specified, then \fBmaster\fR is
|
|
used\.
|
|
Examples:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
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
|
|
.fi
|
|
.RE
|
|
|
|
.RE
|
|
.P
|
|
You may combine multiple arguments, and even multiple types of arguments\.
|
|
For example:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install sax@">=0\.1\.0 <0\.2\.0" bench supervisor
|
|
.fi
|
|
.RE
|
|
.P
|
|
The \fB\-\-tag\fR 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
|
|
The \fB\-\-force\fR argument will force npm to fetch remote resources even if a
|
|
local copy exists on disk\.
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
npm install sax \-\-force
|
|
.fi
|
|
.RE
|
|
.P
|
|
The \fB\-\-global\fR argument will cause npm to install the package globally
|
|
rather than locally\. See npm help 5 \fBnpm\-folders\fR\|\.
|
|
.P
|
|
The \fB\-\-link\fR argument will cause npm to link global installs into the
|
|
local space in some cases\.
|
|
.P
|
|
The \fB\-\-no\-bin\-links\fR argument will prevent npm from creating symlinks for
|
|
any binaries the package might contain\.
|
|
.P
|
|
The \fB\-\-no\-optional\fR argument will prevent optional dependencies from
|
|
being installed\.
|
|
.P
|
|
The \fB\-\-no\-shrinkwrap\fR argument, which will ignore an available
|
|
shrinkwrap file and use the package\.json instead\.
|
|
.P
|
|
The \fB\-\-nodedir=/path/to/node/source\fR argument will allow npm to find the
|
|
node source code so that npm can compile native modules\.
|
|
.P
|
|
See npm help 7 \fBnpm\-config\fR\|\. Many of the configuration params have some
|
|
effect on installation, since that's most of what npm does\.
|
|
.SH ALGORITHM
|
|
.P
|
|
To install a package, npm uses the following algorithm:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
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)
|
|
.fi
|
|
.RE
|
|
.P
|
|
For this \fBpackage{dep}\fR structure: \fBA{B,C}, B{C}, C{D}\fR,
|
|
this algorithm produces:
|
|
.P
|
|
.RS 2
|
|
.nf
|
|
A
|
|
+\-\- B
|
|
`\-\- C
|
|
`\-\- D
|
|
.fi
|
|
.RE
|
|
.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
|
|
See npm help 5 folders for a more detailed description of the specific
|
|
folder structures that npm creates\.
|
|
.SS Limitations of npm's Install Algorithm
|
|
.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
|
|
.RS 2
|
|
.nf
|
|
A \-> B \-> A' \-> B' \-> A \-> B \-> A' \-> B' \-> A \-> \.\.\.
|
|
.fi
|
|
.RE
|
|
.P
|
|
where \fBA\fR is some version of a package, and \fBA'\fR is a different version
|
|
of the same package\. Because \fBB\fR depends on a different version of \fBA\fR
|
|
than the one that is already in the tree, it must install a separate
|
|
copy\. The same is true of \fBA'\fR, which must install \fBB'\fR\|\. Because \fBB'\fR
|
|
depends on the original version of \fBA\fR, which has been overridden, the
|
|
cycle falls into infinite regress\.
|
|
.P
|
|
To avoid this situation, npm flat\-out refuses to install any
|
|
\fBname@version\fR 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\.
|
|
.SH SEE ALSO
|
|
.RS 0
|
|
.IP \(bu 2
|
|
npm help 5 folders
|
|
.IP \(bu 2
|
|
npm help update
|
|
.IP \(bu 2
|
|
npm help link
|
|
.IP \(bu 2
|
|
npm help rebuild
|
|
.IP \(bu 2
|
|
npm help 7 scripts
|
|
.IP \(bu 2
|
|
npm help build
|
|
.IP \(bu 2
|
|
npm help config
|
|
.IP \(bu 2
|
|
npm help 7 config
|
|
.IP \(bu 2
|
|
npm help 5 npmrc
|
|
.IP \(bu 2
|
|
npm help 7 registry
|
|
.IP \(bu 2
|
|
npm help tag
|
|
.IP \(bu 2
|
|
npm help rm
|
|
.IP \(bu 2
|
|
npm help shrinkwrap
|
|
|
|
.RE
|
|
|
|
|