<!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">

  <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 &lt;tarball file&gt;
npm install &lt;tarball url&gt;
npm install &lt;folder&gt;
npm install &lt;name&gt; [--save|--save-dev|--save-optional]
npm install &lt;name&gt;@&lt;tag&gt;
npm install &lt;name&gt;@&lt;version&gt;
npm install &lt;name&gt;@&lt;version range&gt;
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">npm-shrinkwrap(1)</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>&lt;name&gt;@&lt;version&gt;</code> that is published on the registry with (c)</li><li>e) a <code>&lt;name&gt;@&lt;tag&gt;</code> that points to (d)</li><li>f) a <code>&lt;name&gt;</code> that has a &quot;latest&quot; tag satisfying (e)</li><li>g) a <code>&lt;git remote url&gt;</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 &lt;folder&gt;</code>:</p><p>Install a package that is sitting in a folder on the filesystem.</p></li><li><p><code>npm install &lt;tarball file&gt;</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 &lt;tarball url&gt;</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 &quot;http://&quot; or &quot;https://&quot;</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 &lt;name&gt; [--save|--save-dev|--save-optional]</code>:</p><p>Do a <code>&lt;name&gt;@&lt;tag&gt;</code> install, where <code>&lt;tag&gt;</code> is the &quot;tag&quot; config. (See
<code><a href="../misc/npm-config.html">npm-config(7)</a></code>.)</p><p>In most cases, this will install the latest version
of the module published on npm.</p><p>Example:</p><p>      npm install sax</p><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>Examples:</p><p>  npm install sax --save
  npm install node-tap --save-dev
  npm install dtrace-provider --save-optional</p><p><strong>Note</strong>: If there is a file or folder named <code>&lt;name&gt;</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.</p></li></ul></li><li><p><code>npm install &lt;name&gt;@&lt;tag&gt;</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</code></pre></li><li><p><code>npm install &lt;name&gt;@&lt;version&gt;</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</code></pre></li><li><p><code>npm install &lt;name&gt;@&lt;version range&gt;</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">package.json(5)</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><p>      npm install sax@&quot;&gt;=0.1.0 &lt;0.2.0&quot;</p></li><li><p><code>npm install &lt;git remote url&gt;</code>:</p><p>Install a package by cloning a git remote url.  The format of the git
url is:</p><p>      &lt;protocol&gt;://[&lt;user&gt;@]&lt;hostname&gt;&lt;separator&gt;&lt;path&gt;[#&lt;commit-ish&gt;]</p><p><code>&lt;protocol&gt;</code> is one of <code>git</code>, <code>git+ssh</code>, <code>git+http</code>, or
<code>git+https</code>.  If no <code>&lt;commit-ish&gt;</code> is specified, then <code>master</code> is
used.</p><p>Examples:</p><pre><code>  git+ssh://git@github.com:isaacs/npm.git#v1.0.27
  git+https://isaacs@github.com/isaacs/npm.git
  git://github.com/isaacs/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@&quot;&gt;=0.1.0 &lt;0.2.0&quot; 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">npm-folders(5)</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">npm-config(7)</a></code>.  Many of the configuration params have some
effect on installation, since that&#39;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 &lt;where&gt;/node_modules/&lt;what&gt;
for each dep in what.dependencies
  resolve dep to precise version
for each dep@version in what.dependencies
    not in &lt;where&gt;/node_modules/&lt;what&gt;/node_modules/*
    and not in &lt;family&gt;
  add precise version deps to &lt;family&gt;
  install(&lt;where&gt;/node_modules/&lt;what&gt;, 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">npm-folders(5)</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&#39;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 -&gt; B -&gt; A&#39; -&gt; B&#39; -&gt; A -&gt; B -&gt; A&#39; -&gt; B&#39; -&gt; A -&gt; ...</code></pre>

<p>where <code>A</code> is some version of a package, and <code>A&#39;</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&#39;</code>, which must install <code>B&#39;</code>.  Because <code>B&#39;</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">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>
<p id="footer">npm-install &mdash; npm@1.3.21</p>
<script>
;(function () {
var wrapper = document.getElementById("wrapper")
var els = Array.prototype.slice.call(wrapper.getElementsByTagName("*"), 0)
  .filter(function (el) {
    return el.parentNode === wrapper
        && el.tagName.match(/H[1-6]/)
        && el.id
  })
var l = 2
  , toc = document.createElement("ul")
toc.innerHTML = els.map(function (el) {
  var i = el.tagName.charAt(1)
    , out = ""
  while (i > l) {
    out += "<ul>"
    l ++
  }
  while (i < l) {
    out += "</ul>"
    l --
  }
  out += "<li><a href='#" + el.id + "'>" +
    ( el.innerText || el.text || el.innerHTML)
    + "</a>"
  return out
}).join("\n")
toc.id = "toc"
document.body.appendChild(toc)
})()
</script>