3 <title>npm-install</title>
5 <link rel="stylesheet" type="text/css" href="../../static/style.css">
6 <link rel="canonical" href="https://www.npmjs.org/doc/cli/npm-install.html">
7 <script async=true src="../../static/toc.js"></script>
12 <h1><a href="../cli/npm-install.html">npm-install</a></h1> <p>Install a package</p>
13 <h2 id="synopsis">SYNOPSIS</h2>
14 <pre><code>npm install (with no args in a package dir)
15 npm install <tarball file>
16 npm install <tarball url>
17 npm install <folder>
18 npm install [@<scope>/]<name> [--save|--save-dev|--save-optional] [--save-exact] [--save-bundle]
19 npm install [@<scope>/]<name>@<tag>
20 npm install [@<scope>/]<name>@<version>
21 npm install [@<scope>/]<name>@<version range>
22 npm i (with any of the previous argument usage)
23 </code></pre><h2 id="description">DESCRIPTION</h2>
24 <p>This command installs a package, and any packages that it depends on. If the
25 package has a shrinkwrap file, the installation of dependencies will be driven
26 by that. See <a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a>.</p>
27 <p>A <code>package</code> is:</p>
29 <li>a) a folder containing a program described by a <code><a href="../files/package.json.html">package.json(5)</a></code> file</li>
30 <li>b) a gzipped tarball containing (a)</li>
31 <li>c) a url that resolves to (b)</li>
32 <li>d) a <code><name>@<version></code> that is published on the registry (see <code><a href="../misc/npm-registry.html">npm-registry(7)</a></code>) with (c)</li>
33 <li>e) a <code><name>@<tag></code> (see <code><a href="../cli/npm-dist-tag.html">npm-dist-tag(1)</a></code>) that points to (d)</li>
34 <li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li>
35 <li>g) a <code><git remote url></code> that resolves to (b)</li>
37 <p>Even if you never publish your package, you can still get a lot of
38 benefits of using npm if you just want to write a node program (a), and
39 perhaps if you also want to be able to easily install it elsewhere
40 after packing it up into a tarball (b).</p>
42 <li><p><code>npm install</code> (in package directory, no arguments):</p>
43 <p> Install the dependencies in the local node_modules folder.</p>
44 <p> In global mode (ie, with <code>-g</code> or <code>--global</code> appended to the command),
45 it installs the current package context (ie, the current working
46 directory) as a global package.</p>
47 <p> By default, <code>npm install</code> will install all modules listed as dependencies
48 in <code><a href="../files/package.json.html">package.json(5)</a></code>.</p>
49 <p> With the <code>--production</code> flag (or when the <code>NODE_ENV</code> environment variable
50 is set to <code>production</code>), npm will not install modules listed in
51 <code>devDependencies</code>.</p>
53 <li><p><code>npm install <folder></code>:</p>
54 <p> Install a package that is sitting in a folder on the filesystem.</p>
56 <li><p><code>npm install <tarball file></code>:</p>
57 <p> Install a package that is sitting on the filesystem. Note: if you just want
58 to link a dev directory into your npm root, you can do this more easily by
59 using <code>npm link</code>.</p>
61 <pre><code> npm install ./package.tgz
63 <li><p><code>npm install <tarball url></code>:</p>
64 <p> Fetch the tarball url, and then install it. In order to distinguish between
65 this and other options, the argument must start with "http://" or "https://"</p>
67 <pre><code> npm install https://github.com/indexzero/forever/tarball/v0.5.6
69 <li><p><code>npm install [@<scope>/]<name> [--save|--save-dev|--save-optional]</code>:</p>
70 <p> Do a <code><name>@<tag></code> install, where <code><tag></code> is the "tag" config. (See
71 <code><a href="../misc/npm-config.html">npm-config(7)</a></code>. The config's default value is <code>latest</code>.)</p>
72 <p> In most cases, this will install the latest version
73 of the module published on npm.</p>
75 <pre><code> npm install sax
76 </code></pre><p> <code>npm install</code> takes 3 exclusive, optional flags which save or update
77 the package version in your main package.json:</p>
79 <li><p><code>--save</code>: Package will appear in your <code>dependencies</code>.</p>
81 <li><p><code>--save-dev</code>: Package will appear in your <code>devDependencies</code>.</p>
83 <li><p><code>--save-optional</code>: Package will appear in your <code>optionalDependencies</code>.</p>
84 <p>When using any of the above options to save dependencies to your
85 package.json, there are two additional, optional flags:</p>
87 <li><p><code>--save-exact</code>: Saved dependencies will be configured with an
88 exact version rather than using npm's default semver range
91 <li><p><code>-B, --save-bundle</code>: Saved dependencies will also be added to your <code>bundleDependencies</code> list.</p>
92 <p>Note: if you do not include the @-symbol on your scope name, npm will
93 interpret this as a GitHub repository instead, see below. Scopes names
94 must also be followed by a slash.</p>
96 <pre><code>npm install sax --save
97 npm install githubname/reponame
98 npm install @myorg/privatepackage
99 npm install node-tap --save-dev
100 npm install dtrace-provider --save-optional
101 npm install readable-stream --save --save-exact
102 npm install ansi-regex --save --save-bundle
107 <pre><code>**Note**: If there is a file or folder named `<name>` in the current
108 working directory, then it will try to install that, and only try to
109 fetch the package by name if it is not valid.
111 <li><p><code>npm install [@<scope>/]<name>@<tag></code>:</p>
112 <p> Install the version of the package that is referenced by the specified tag.
113 If the tag does not exist in the registry data for that package, then this
116 <pre><code> npm install sax@latest
117 npm install @myorg/mypackage@latest
119 <li><p><code>npm install [@<scope>/]<name>@<version></code>:</p>
120 <p> Install the specified version of the package. This will fail if the
121 version has not been published to the registry.</p>
123 <pre><code> npm install sax@0.1.1
124 npm install @myorg/privatepackage@1.5.0
126 <li><p><code>npm install [@<scope>/]<name>@<version range></code>:</p>
127 <p> Install a version of the package matching the specified version range. This
128 will follow the same rules for resolving dependencies described in <code><a href="../files/package.json.html">package.json(5)</a></code>.</p>
129 <p> Note that most version ranges must be put in quotes so that your shell will
130 treat it as a single argument.</p>
132 <pre><code> npm install sax@">=0.1.0 <0.2.0"
133 npm install @myorg/privatepackage@">=0.1.0 <0.2.0"
135 <li><p><code>npm install <git remote url></code>:</p>
136 <p> Install a package by cloning a git remote url. The format of the git
138 <pre><code> <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:/]<path>[#<commit-ish>]
139 </code></pre><p> <code><protocol></code> is one of <code>git</code>, <code>git+ssh</code>, <code>git+http</code>, or
140 <code>git+https</code>. If no <code><commit-ish></code> is specified, then <code>master</code> is
142 <p> The following git environment variables are recognized by npm and will be added
143 to the environment when running git:</p>
145 <li><code>GIT_ASKPASS</code></li>
146 <li><code>GIT_EXEC_PATH</code></li>
147 <li><code>GIT_PROXY_COMMAND</code></li>
148 <li><code>GIT_SSH</code></li>
149 <li><code>GIT_SSH_COMMAND</code></li>
150 <li><code>GIT_SSL_CAINFO</code></li>
151 <li><p><code>GIT_SSL_NO_VERIFY</code></p>
152 <p>See the git man page for details.</p>
154 <pre><code>npm install git+ssh://git@github.com:npm/npm.git#v1.0.27
155 npm install git+https://isaacs@github.com/npm/npm.git
156 npm install git://github.com/npm/npm.git#v1.0.27
157 GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/npm.git
161 <li><p><code>npm install <githubname>/<githubrepo>[#<commit-ish>]</code>:</p>
163 <li><p><code>npm install github:<githubname>/<githubrepo>[#<commit-ish>]</code>:</p>
164 <p> Install the package at <code>https://github.com/githubname/githubrepo</code> by
165 attempting to clone it using <code>git</code>.</p>
166 <p> If you don't specify a <em>commit-ish</em> then <code>master</code> will be used.</p>
168 <pre><code> npm install mygithubuser/myproject
169 npm install github:mygithubuser/myproject
171 <li><p><code>npm install gist:[<githubname>/]<gistID>[#<commit-ish>]</code>:</p>
172 <p> Install the package at <code>https://gist.github.com/gistID</code> by attempting to
173 clone it using <code>git</code>. The GitHub username associated with the gist is
174 optional and will not be saved in <code>package.json</code> if <code>--save</code> is used.</p>
175 <p> If you don't specify a <em>commit-ish</em> then <code>master</code> will be used.</p>
177 <pre><code> npm install gist:101a11beef
179 <li><p><code>npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]</code>:</p>
180 <p> Install the package at <code>https://bitbucket.org/bitbucketname/bitbucketrepo</code>
181 by attempting to clone it using <code>git</code>.</p>
182 <p> If you don't specify a <em>commit-ish</em> then <code>master</code> will be used.</p>
184 <pre><code> npm install bitbucket:mybitbucketuser/myproject
186 <li><p><code>npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]</code>:</p>
187 <p> Install the package at <code>https://gitlab.com/gitlabname/gitlabrepo</code>
188 by attempting to clone it using <code>git</code>.</p>
189 <p> If you don't specify a <em>commit-ish</em> then <code>master</code> will be used.</p>
191 <pre><code> npm install gitlab:mygitlabuser/myproject
194 <p>You may combine multiple arguments, and even multiple types of arguments.
196 <pre><code>npm install sax@">=0.1.0 <0.2.0" bench supervisor
197 </code></pre><p>The <code>--tag</code> argument will apply to all of the specified install targets. If a
198 tag with the given name exists, the tagged version is preferred over newer
200 <p>The <code>--force</code> argument will force npm to fetch remote resources even if a
201 local copy exists on disk.</p>
202 <pre><code>npm install sax --force
203 </code></pre><p>The <code>--global</code> argument will cause npm to install the package globally
204 rather than locally. See <code><a href="../files/npm-folders.html">npm-folders(5)</a></code>.</p>
205 <p>The <code>--ignore-scripts</code> argument will cause npm to not execute any
206 scripts defined in the package.json. See <code><a href="../misc/npm-scripts.html">npm-scripts(7)</a></code>.</p>
207 <p>The <code>--link</code> argument will cause npm to link global installs into the
208 local space in some cases.</p>
209 <p>The <code>--no-bin-links</code> argument will prevent npm from creating symlinks for
210 any binaries the package might contain.</p>
211 <p>The <code>--no-optional</code> argument will prevent optional dependencies from
213 <p>The <code>--no-shrinkwrap</code> argument, which will ignore an available
214 shrinkwrap file and use the package.json instead.</p>
215 <p>The <code>--nodedir=/path/to/node/source</code> argument will allow npm to find the
216 node source code so that npm can compile native modules.</p>
217 <p>See <code><a href="../misc/npm-config.html">npm-config(7)</a></code>. Many of the configuration params have some
218 effect on installation, since that's most of what npm does.</p>
219 <h2 id="algorithm">ALGORITHM</h2>
220 <p>To install a package, npm uses the following algorithm:</p>
221 <pre><code>install(where, what, family, ancestors)
222 fetch what, unpack to <where>/node_modules/<what>
223 for each dep in what.dependencies
224 resolve dep to precise version
225 for each dep@version in what.dependencies
226 not in <where>/node_modules/<what>/node_modules/*
227 and not in <family>
228 add precise version deps to <family>
229 install(<where>/node_modules/<what>, dep, family)
230 </code></pre><p>For this <code>package{dep}</code> structure: <code>A{B,C}, B{C}, C{D}</code>,
231 this algorithm produces:</p>
236 </code></pre><p>That is, the dependency from B to C is satisfied by the fact that A
237 already caused C to be installed at a higher level.</p>
238 <p>See <a href="../files/npm-folders.html">npm-folders(5)</a> for a more detailed description of the specific
239 folder structures that npm creates.</p>
240 <h3 id="limitations-of-npm-s-install-algorithm">Limitations of npm's Install Algorithm</h3>
241 <p>There are some very rare and pathological edge-cases where a cycle can
242 cause npm to try to install a never-ending tree of packages. Here is
243 the simplest case:</p>
244 <pre><code>A -> B -> A' -> B' -> A -> B -> A' -> B' -> A -> ...
245 </code></pre><p>where <code>A</code> is some version of a package, and <code>A'</code> is a different version
246 of the same package. Because <code>B</code> depends on a different version of <code>A</code>
247 than the one that is already in the tree, it must install a separate
248 copy. The same is true of <code>A'</code>, which must install <code>B'</code>. Because <code>B'</code>
249 depends on the original version of <code>A</code>, which has been overridden, the
250 cycle falls into infinite regress.</p>
251 <p>To avoid this situation, npm flat-out refuses to install any
252 <code>name@version</code> that is already present anywhere in the tree of package
253 folder ancestors. A more correct, but more complex, solution would be
254 to symlink the existing version into the new location. If this ever
255 affects a real use-case, it will be investigated.</p>
256 <h2 id="see-also">SEE ALSO</h2>
258 <li><a href="../files/npm-folders.html">npm-folders(5)</a></li>
259 <li><a href="../cli/npm-update.html">npm-update(1)</a></li>
260 <li><a href="../cli/npm-link.html">npm-link(1)</a></li>
261 <li><a href="../cli/npm-rebuild.html">npm-rebuild(1)</a></li>
262 <li><a href="../misc/npm-scripts.html">npm-scripts(7)</a></li>
263 <li><a href="../cli/npm-build.html">npm-build(1)</a></li>
264 <li><a href="../cli/npm-config.html">npm-config(1)</a></li>
265 <li><a href="../misc/npm-config.html">npm-config(7)</a></li>
266 <li><a href="../files/npmrc.html">npmrc(5)</a></li>
267 <li><a href="../misc/npm-registry.html">npm-registry(7)</a></li>
268 <li><a href="../cli/npm-tag.html">npm-tag(1)</a></li>
269 <li><a href="../cli/npm-uninstall.html">npm-uninstall(1)</a></li>
270 <li><a href="../cli/npm-shrinkwrap.html">npm-shrinkwrap(1)</a></li>
271 <li><a href="../files/package.json.html">package.json(5)</a></li>
276 <table border=0 cellspacing=0 cellpadding=0 id=npmlogo>
277 <tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr>
278 <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>
279 <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>
280 <tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr>
281 <tr><td style="width:10px;height:10px;background:#fff"> </td></tr>
282 <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>
283 <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>
285 <p id="footer">npm-install — npm@2.15.11</p>