npm

<!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"> <script async=true src="../../static/toc.js"></script> <body> <div id="wrapper"> <h1><a href="../cli/npm-install.html">npm-install</a></h1> Install a package <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 <name> [--save|--save-dev|--save-optional] [--save-exact] npm install <name>@<tag> npm install <name>@<version> npm install <name>@<version range> npm i (with any of the previous argument usage)</code></pre> <h2 id="DESCRIPTION">DESCRIPTION</h2> 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">npm-shrinkwrap(1)</a>. A <code>package</code> is: <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 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> 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). <ul><li><code>npm install</code> (in package directory, no arguments):Install the dependencies in the local node_modules folder.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.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>.</li><li><code>npm install <folder></code>:Install a package that is sitting in a folder on the filesystem.</li><li><code>npm install <tarball file></code>: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>.Example:<pre><code> npm install ./package.tgz</code></pre></li><li><code>npm install <tarball url></code>: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:<pre><code> npm install https://github.com/indexzero/forever/tarball/v0.5.6</code></pre></li><li><code>npm install <name> [--save|--save-dev|--save-optional]</code>:Do a <code><name>@<tag></code> install, where <code><tag></code> is the "tag" config. (See <code><a href="../misc/npm-config.html">npm-config(7)</a></code>.)In most cases, this will install the latest version of the module published on npm.Example: npm install sax<code>npm install</code> takes 3 exclusive, optional flags which save or update the package version in your main package.json:<ul><li><code>--save</code>: Package will appear in your <code>dependencies</code>.</li><li><code>--save-dev</code>: Package will appear in your <code>devDependencies</code>.</li><li><code>--save-optional</code>: Package will appear in your <code>optionalDependencies</code>.When using any of the above options to save dependencies to your package.json, there is an additional, optional flag:</li><li><code>--save-exact</code>: Saved dependencies will be configured with an exact version rather than using npm's default semver range operator.Examples: npm install sax --save npm install node-tap --save-dev npm install dtrace-provider --save-optional npm install readable-stream --save --save-exactNote: If there is a file or folder named <code><name></code> 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.</li></ul></li><li><code>npm install <name>@<tag></code>: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:<pre><code> npm install sax@latest</code></pre></li><li><code>npm install <name>@<version></code>:Install the specified version of the package. This will fail if the version has not been published to the registry.Example:<pre><code> npm install sax@0.1.1</code></pre></li><li><code>npm install <name>@<version range></code>: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">package.json(5)</a></code>.Note that most version ranges must be put in quotes so that your shell will treat it as a single argument.Example: npm install sax@">=0.1.0 <0.2.0"</li><li><code>npm install <git remote url></code>:Install a package by cloning a git remote url. The format of the git url is: <protocol>://[<user>@]<hostname><separator><path>[#<commit-ish>]<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.Examples:<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> You may combine multiple arguments, and even multiple types of arguments. For example: <pre><code>npm install sax@">=0.1.0 <0.2.0" bench supervisor</code></pre> 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. The <code>--force</code> argument will force npm to fetch remote resources even if a local copy exists on disk. <pre><code>npm install sax --force</code></pre> The <code>--global</code> argument will cause npm to install the package globally rather than locally. See <code><a href="../files/npm-folders.html">npm-folders(5)</a></code>. The <code>--link</code> argument will cause npm to link global installs into the local space in some cases. The <code>--no-bin-links</code> argument will prevent npm from creating symlinks for any binaries the package might contain. The <code>--no-optional</code> argument will prevent optional dependencies from being installed. The <code>--no-shrinkwrap</code> argument, which will ignore an available shrinkwrap file and use the package.json instead. 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. See <code><a href="../misc/npm-config.html">npm-config(7)</a></code>. Many of the configuration params have some effect on installation, since that's most of what npm does. <h2 id="ALGORITHM">ALGORITHM</h2> To install a package, npm uses the following algorithm: <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> For this <code>package{dep}</code> structure: <code>A{B,C}, B{C}, C{D}</code>, this algorithm produces: <pre><code>A +-- B `-- C `-- D</code></pre> 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. See <a href="../files/npm-folders.html">npm-folders(5)</a> for a more detailed description of the specific folder structures that npm creates. <h3 id="Limitations-of-npm-s-Install-Algorithm">Limitations of npm's Install Algorithm</h3> 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: <pre><code>A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...</code></pre> 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. 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. <h2 id="SEE-ALSO">SEE ALSO</h2> <ul><li><a href="../files/npm-folders.html">npm-folders(5)</a></li><li><a href="../cli/npm-update.html">npm-update(1)</a></li><li><a href="../cli/npm-link.html">npm-link(1)</a></li><li><a href="../cli/npm-rebuild.html">npm-rebuild(1)</a></li><li><a href="../misc/npm-scripts.html">npm-scripts(7)</a></li><li><a href="../cli/npm-build.html">npm-build(1)</a></li><li><a href="../cli/npm-config.html">npm-config(1)</a></li><li><a href="../misc/npm-config.html">npm-config(7)</a></li><li><a href="../files/npmrc.html">npmrc(5)</a></li><li><a href="../misc/npm-registry.html">npm-registry(7)</a></li><li><a href="../files/npm-folders.html">npm-folders(5)</a></li><li><a href="../cli/npm-tag.html">npm-tag(1)</a></li><li><a href="../cli/npm-rm.html">npm-rm(1)</a></li><li><a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</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> npm-install — npm@1.4.5