4 <meta http-equiv="content-type" value="text/html;utf-8">
5 <link rel="stylesheet" type="text/css" href="../../static/style.css">
6 <link rel="canonical" href="https://www.npmjs.org/doc/misc/npm-faq.html">
7 <script async=true src="../../static/toc.js"></script>
12 <h1><a href="../misc/npm-faq.html">npm-faq</a></h1> <p>Frequently Asked Questions</p>
13 <h2 id="where-can-i-find-these-docs-in-html-">Where can I find these docs in HTML?</h2>
14 <p><a href="https://docs.npmjs.com/">https://docs.npmjs.com/</a>, or run:</p>
15 <pre><code>npm config set viewer browser
16 </code></pre><p>to open these documents in your default web browser rather than <code>man</code>.</p>
17 <h2 id="it-didn-t-work-">It didn't work.</h2>
18 <p>That's not really a question.</p>
19 <h2 id="why-didn-t-it-work-">Why didn't it work?</h2>
20 <p>I don't know yet.</p>
21 <p>Read the error output, and if you can't figure out what it means,
22 do what it says and post a bug with all the information it asks for.</p>
23 <h2 id="where-does-npm-put-stuff-">Where does npm put stuff?</h2>
24 <p>See <code><a href="../files/npm-folders.html">npm-folders(5)</a></code></p>
27 <li>Use the <code>npm root</code> command to see where modules go, and the <code>npm bin</code>
28 command to see where executables go</li>
29 <li>Global installs are different from local installs. If you install
30 something with the <code>-g</code> flag, then its executables go in <code>npm bin -g</code>
31 and its modules go in <code>npm root -g</code>.</li>
33 <h2 id="how-do-i-install-something-on-my-computer-in-a-central-location-">How do I install something on my computer in a central location?</h2>
34 <p>Install it globally by tacking <code>-g</code> or <code>--global</code> to the command. (This
35 is especially important for command line utilities that need to add
36 their bins to the global system <code>PATH</code>.)</p>
37 <h2 id="i-installed-something-globally-but-i-can-t-require-it">I installed something globally, but I can't <code>require()</code> it</h2>
38 <p>Install it locally.</p>
39 <p>The global install location is a place for command-line utilities
40 to put their bins in the system <code>PATH</code>. It's not for use with <code>require()</code>.</p>
41 <p>If you <code>require()</code> a module in your code, then that means it's a
42 dependency, and a part of your program. You need to install it locally
44 <h2 id="why-can-t-npm-just-put-everything-in-one-place-like-other-package-managers-">Why can't npm just put everything in one place, like other package managers?</h2>
45 <p>Not every change is an improvement, but every improvement is a change.
46 This would be like asking git to do network IO for every commit. It's
47 not going to happen, because it's a terrible idea that causes more
48 problems than it solves.</p>
49 <p>It is much harder to avoid dependency conflicts without nesting
50 dependencies. This is fundamental to the way that npm works, and has
51 proven to be an extremely successful approach. See <code><a href="../files/npm-folders.html">npm-folders(5)</a></code> for
53 <p>If you want a package to be installed in one place, and have all your
54 programs reference the same copy of it, then use the <code>npm link</code> command.
55 That's what it's for. Install it globally, then link it into each
56 program that uses it.</p>
57 <h2 id="whatever-i-really-want-the-old-style-everything-global-style-">Whatever, I really want the old style 'everything global' style.</h2>
58 <p>Write your own package manager. You could probably even wrap up <code>npm</code>
59 in a shell script if you really wanted to.</p>
60 <p>npm will not help you do something that is known to be a bad idea.</p>
61 <h2 id="should-i-check-my-node_modules-folder-into-git-">Should I check my <code>node_modules</code> folder into git?</h2>
62 <p>Usually, no. Allow npm to resolve dependencies for your packages.</p>
63 <p>For packages you <strong>deploy</strong>, such as websites and apps,
64 you should use npm shrinkwrap to lock down your full dependency tree:</p>
65 <p><a href="https://docs.npmjs.com/cli/shrinkwrap">https://docs.npmjs.com/cli/shrinkwrap</a></p>
66 <p>If you are paranoid about depending on the npm ecosystem,
67 you should run a private npm mirror or a private cache.</p>
68 <p>If you want 100% confidence in being able to reproduce the specific bytes
69 included in a deployment, you should use an additional mechanism that can
70 verify contents rather than versions. For example,
71 Amazon machine images, DigitalOcean snapshots, Heroku slugs, or simple tarballs.</p>
72 <h2 id="is-it-npm-or-npm-or-npm-">Is it 'npm' or 'NPM' or 'Npm'?</h2>
73 <p>npm should never be capitalized unless it is being displayed in a
74 location that is customarily all-caps (such as the title of man pages.)</p>
75 <h2 id="if-npm-is-an-acronym-why-is-it-never-capitalized-">If 'npm' is an acronym, why is it never capitalized?</h2>
76 <p>Contrary to the belief of many, "npm" is not in fact an abbreviation for
77 "Node Package Manager". It is a recursive bacronymic abbreviation for
78 "npm is not an acronym". (If it was "ninaa", then it would be an
79 acronym, and thus incorrectly named.)</p>
80 <p>"NPM", however, <em>is</em> an acronym (more precisely, a capitonym) for the
81 National Association of Pastoral Musicians. You can learn more
82 about them at <a href="http://npm.org/">http://npm.org/</a>.</p>
83 <p>In software, "NPM" is a Non-Parametric Mapping utility written by
84 Chris Rorden. You can analyze pictures of brains with it. Learn more
85 about the (capitalized) NPM program at <a href="http://www.cabiatl.com/mricro/npm/">http://www.cabiatl.com/mricro/npm/</a>.</p>
86 <p>The first seed that eventually grew into this flower was a bash utility
87 named "pm", which was a shortened descendent of "pkgmakeinst", a
88 bash function that was used to install various different things on different
89 platforms, most often using Yahoo's <code>yinst</code>. If <code>npm</code> was ever an
90 acronym for anything, it was <code>node pm</code> or maybe <code>new pm</code>.</p>
91 <p>So, in all seriousness, the "npm" project is named after its command-line
92 utility, which was organically selected to be easily typed by a right-handed
93 programmer using a US QWERTY keyboard layout, ending with the
94 right-ring-finger in a postition to type the <code>-</code> key for flags and
95 other command-line arguments. That command-line utility is always
96 lower-case, though it starts most sentences it is a part of.</p>
97 <h2 id="how-do-i-list-installed-packages-">How do I list installed packages?</h2>
98 <p><code>npm ls</code></p>
99 <h2 id="how-do-i-search-for-packages-">How do I search for packages?</h2>
100 <p><code>npm search</code></p>
101 <p>Arguments are greps. <code>npm search jsdom</code> shows jsdom packages.</p>
102 <h2 id="how-do-i-update-npm-">How do I update npm?</h2>
103 <pre><code>npm install npm -g
104 </code></pre><p>You can also update all outdated local packages by doing <code>npm update</code> without
105 any arguments, or global packages by doing <code>npm update -g</code>.</p>
106 <p>Occasionally, the version of npm will progress such that the current
107 version cannot be properly installed with the version that you have
108 installed already. (Consider, if there is ever a bug in the <code>update</code>
110 <p>In those cases, you can do this:</p>
111 <pre><code>curl https://www.npmjs.com/install.sh | sh
112 </code></pre><h2 id="what-is-a-package-">What is a <code>package</code>?</h2>
115 <li>a) a folder containing a program described by a package.json file</li>
116 <li>b) a gzipped tarball containing (a)</li>
117 <li>c) a url that resolves to (b)</li>
118 <li>d) a <code><name>@<version></code> that is published on the registry with (c)</li>
119 <li>e) a <code><name>@<tag></code> that points to (d)</li>
120 <li>f) a <code><name></code> that has a "latest" tag satisfying (e)</li>
121 <li>g) a <code>git</code> url that, when cloned, results in (a).</li>
123 <p>Even if you never publish your package, you can still get a lot of
124 benefits of using npm if you just want to write a node program (a), and
125 perhaps if you also want to be able to easily install it elsewhere
126 after packing it up into a tarball (b).</p>
127 <p>Git urls can be of the form:</p>
128 <pre><code>git://github.com/user/project.git#commit-ish
129 git+ssh://user@hostname:project.git#commit-ish
130 git+http://user@hostname/project/blah.git#commit-ish
131 git+https://user@hostname/project/blah.git#commit-ish
132 </code></pre><p>The <code>commit-ish</code> can be any tag, sha, or branch which can be supplied as
133 an argument to <code>git checkout</code>. The default is <code>master</code>.</p>
134 <h2 id="what-is-a-module-">What is a <code>module</code>?</h2>
135 <p>A module is anything that can be loaded with <code>require()</code> in a Node.js
136 program. The following things are all examples of things that can be
137 loaded as modules:</p>
139 <li>A folder with a <code>package.json</code> file containing a <code>main</code> field.</li>
140 <li>A folder with an <code>index.js</code> file in it.</li>
141 <li>A JavaScript file.</li>
143 <p>Most npm packages are modules, because they are libraries that you
144 load with <code>require</code>. However, there's no requirement that an npm
145 package be a module! Some only contain an executable command-line
146 interface, and don't provide a <code>main</code> field for use in Node programs.</p>
147 <p>Almost all npm packages (at least, those that are Node programs)
148 <em>contain</em> many modules within them (because every file they load with
149 <code>require()</code> is a module).</p>
150 <p>In the context of a Node program, the <code>module</code> is also the thing that
151 was loaded <em>from</em> a file. For example, in the following program:</p>
152 <pre><code>var req = require('request')
153 </code></pre><p>we might say that "The variable <code>req</code> refers to the <code>request</code> module".</p>
154 <h2 id="so-why-is-it-the-node_modules-folder-but-package-json-file-why-not-node_packages-or-module-json-">So, why is it the "<code>node_modules</code>" folder, but "<code>package.json</code>" file? Why not <code>node_packages</code> or <code>module.json</code>?</h2>
155 <p>The <code>package.json</code> file defines the package. (See "What is a
156 package?" above.)</p>
157 <p>The <code>node_modules</code> folder is the place Node.js looks for modules.
158 (See "What is a module?" above.)</p>
159 <p>For example, if you create a file at <code>node_modules/foo.js</code> and then
160 had a program that did <code>var f = require('foo.js')</code> then it would load
161 the module. However, <code>foo.js</code> is not a "package" in this case,
162 because it does not have a package.json.</p>
163 <p>Alternatively, if you create a package which does not have an
164 <code>index.js</code> or a <code>"main"</code> field in the <code>package.json</code> file, then it is
165 not a module. Even if it's installed in <code>node_modules</code>, it can't be
166 an argument to <code>require()</code>.</p>
167 <h2 id="-node_modules-is-the-name-of-my-deity-s-arch-rival-and-a-forbidden-word-in-my-religion-can-i-configure-npm-to-use-a-different-folder-"><code>"node_modules"</code> is the name of my deity's arch-rival, and a Forbidden Word in my religion. Can I configure npm to use a different folder?</h2>
168 <p>No. This will never happen. This question comes up sometimes,
169 because it seems silly from the outside that npm couldn't just be
170 configured to put stuff somewhere else, and then npm could load them
171 from there. It's an arbitrary spelling choice, right? What's the big
173 <p>At the time of this writing, the string <code>'node_modules'</code> appears 151
174 times in 53 separate files in npm and node core (excluding tests and
176 <p>Some of these references are in node's built-in module loader. Since
177 npm is not involved <strong>at all</strong> at run-time, node itself would have to
178 be configured to know where you've decided to stick stuff. Complexity
179 hurdle #1. Since the Node module system is locked, this cannot be
180 changed, and is enough to kill this request. But I'll continue, in
181 deference to your deity's delicate feelings regarding spelling.</p>
182 <p>Many of the others are in dependencies that npm uses, which are not
183 necessarily tightly coupled to npm (in the sense that they do not read
184 npm's configuration files, etc.) Each of these would have to be
185 configured to take the name of the <code>node_modules</code> folder as a
186 parameter. Complexity hurdle #2.</p>
187 <p>Furthermore, npm has the ability to "bundle" dependencies by adding
188 the dep names to the <code>"bundledDependencies"</code> list in package.json,
189 which causes the folder to be included in the package tarball. What
190 if the author of a module bundles its dependencies, and they use a
191 different spelling for <code>node_modules</code>? npm would have to rename the
192 folder at publish time, and then be smart enough to unpack it using
193 your locally configured name. Complexity hurdle #3.</p>
194 <p>Furthermore, what happens when you <em>change</em> this name? Fine, it's
195 easy enough the first time, just rename the <code>node_modules</code> folders to
196 <code>./blergyblerp/</code> or whatever name you choose. But what about when you
197 change it again? npm doesn't currently track any state about past
198 configuration settings, so this would be rather difficult to do
199 properly. It would have to track every previous value for this
200 config, and always accept any of them, or else yesterday's install may
201 be broken tomorrow. Complexity hurdle #4.</p>
202 <p>Never going to happen. The folder is named <code>node_modules</code>. It is
203 written indelibly in the Node Way, handed down from the ancient times
205 <h2 id="how-do-i-install-node-with-npm-">How do I install node with npm?</h2>
206 <p>You don't. Try one of these node version managers:</p>
209 <li><a href="http://github.com/isaacs/nave">http://github.com/isaacs/nave</a></li>
210 <li><a href="http://github.com/visionmedia/n">http://github.com/visionmedia/n</a></li>
211 <li><a href="http://github.com/creationix/nvm">http://github.com/creationix/nvm</a></li>
215 <li><a href="http://github.com/marcelklehr/nodist">http://github.com/marcelklehr/nodist</a></li>
216 <li><a href="https://github.com/coreybutler/nvm-windows">https://github.com/coreybutler/nvm-windows</a></li>
217 <li><a href="https://github.com/hakobera/nvmw">https://github.com/hakobera/nvmw</a></li>
218 <li><a href="https://github.com/nanjingboy/nvmw">https://github.com/nanjingboy/nvmw</a></li>
220 <h2 id="how-can-i-use-npm-for-development-">How can I use npm for development?</h2>
221 <p>See <code><a href="../misc/npm-developers.html">npm-developers(7)</a></code> and <code><a href="../files/package.json.html">package.json(5)</a></code>.</p>
222 <p>You'll most likely want to <code>npm link</code> your development folder. That's
224 <p>To set up your own private registry, check out <code><a href="../misc/npm-registry.html">npm-registry(7)</a></code>.</p>
225 <h2 id="can-i-list-a-url-as-a-dependency-">Can I list a url as a dependency?</h2>
226 <p>Yes. It should be a url to a gzipped tarball containing a single folder
227 that has a package.json in its root, or a git url.
228 (See "what is a package?" above.)</p>
229 <h2 id="how-do-i-symlink-to-a-dev-folder-so-i-don-t-have-to-keep-re-installing-">How do I symlink to a dev folder so I don't have to keep re-installing?</h2>
230 <p>See <code><a href="../cli/npm-link.html">npm-link(1)</a></code></p>
231 <h2 id="the-package-registry-website-what-is-that-exactly-">The package registry website. What is that exactly?</h2>
232 <p>See <code><a href="../misc/npm-registry.html">npm-registry(7)</a></code>.</p>
233 <h2 id="i-forgot-my-password-and-can-t-publish-how-do-i-reset-it-">I forgot my password, and can't publish. How do I reset it?</h2>
234 <p>Go to <a href="https://npmjs.com/forgot">https://npmjs.com/forgot</a>.</p>
235 <h2 id="i-get-econnrefused-a-lot-what-s-up-">I get ECONNREFUSED a lot. What's up?</h2>
236 <p>Either the registry is down, or node's DNS isn't able to reach out.</p>
237 <p>To check if the registry is down, open up
238 <a href="https://registry.npmjs.org/">https://registry.npmjs.org/</a> in a web browser. This will also tell
239 you if you are just unable to access the internet for some reason.</p>
240 <p>If the registry IS down, let us know by emailing <a href="mailto:support@npmjs.com">support@npmjs.com</a>
241 or posting an issue at <a href="https://github.com/npm/npm/issues">https://github.com/npm/npm/issues</a>. If it's
242 down for the world (and not just on your local network) then we're
243 probably already being pinged about it.</p>
244 <p>You can also often get a faster response by visiting the #npm channel
246 <h2 id="why-no-namespaces-">Why no namespaces?</h2>
247 <p>npm has only one global namespace. If you want to namespace your own packages,
248 you may: simply use the <code>-</code> character to separate the names or use scoped
249 packages. npm is a mostly anarchic system. There is not sufficient need to
250 impose namespace rules on everyone.</p>
251 <p>As of 2.0, npm supports scoped packages, which allow you to publish a group of
252 related modules without worrying about name collisions.</p>
253 <p>Every npm user owns the scope associated with their username. For example, the
254 user named <code>npm</code> owns the scope <code>@npm</code>. Scoped packages are published inside a
255 scope by naming them as if they were files under the scope directory, e.g., by
256 setting <code>name</code> in <code>package.json</code> to <code>@npm/npm</code>.</p>
257 <p>Scoped packages are supported by the public npm registry. The npm client is
258 backwards-compatible with un-scoped registries, so it can be used to work with
259 scoped and un-scoped registries at the same time.</p>
260 <p>Unscoped packages can only depend on other unscoped packages. Scoped packages
261 can depend on packages from their own scope, a different scope, or the public
262 registry (unscoped).</p>
263 <p>For the current documentation of scoped packages, see
264 <a href="https://docs.npmjs.com/misc/scope">https://docs.npmjs.com/misc/scope</a></p>
267 <li><p>For the reasoning behind the "one global namespace", please see this
268 discussion: <a href="https://github.com/npm/npm/issues/798">https://github.com/npm/npm/issues/798</a> (TL;DR: It doesn't
269 actually make things better, and can make them worse.)</p>
271 <li><p>For the pre-implementation discussion of the scoped package feature, see
272 this discussion: <a href="https://github.com/npm/npm/issues/5239">https://github.com/npm/npm/issues/5239</a></p>
275 <h2 id="who-does-npm-">Who does npm?</h2>
276 <p>npm was originally written by Isaac Z. Schlueter, and many others have
277 contributed to it, some of them quite substantially.</p>
278 <p>The npm open source project, The npm Registry, and <a href="https://www.npmjs.com">the community
279 website</a> are maintained and operated by the
280 good folks at <a href="http://www.npmjs.com">npm, Inc.</a></p>
281 <h2 id="i-have-a-question-or-request-not-addressed-here-where-should-i-put-it-">I have a question or request not addressed here. Where should I put it?</h2>
282 <p>Post an issue on the github project:</p>
284 <li><a href="https://github.com/npm/npm/issues">https://github.com/npm/npm/issues</a></li>
286 <h2 id="why-does-npm-hate-me-">Why does npm hate me?</h2>
287 <p>npm is not capable of hatred. It loves everyone, especially you.</p>
288 <h2 id="see-also">SEE ALSO</h2>
290 <li><a href="../cli/npm.html">npm(1)</a></li>
291 <li><a href="../misc/npm-developers.html">npm-developers(7)</a></li>
292 <li><a href="../files/package.json.html">package.json(5)</a></li>
293 <li><a href="../cli/npm-config.html">npm-config(1)</a></li>
294 <li><a href="../misc/npm-config.html">npm-config(7)</a></li>
295 <li><a href="../files/npmrc.html">npmrc(5)</a></li>
296 <li><a href="../misc/npm-config.html">npm-config(7)</a></li>
297 <li><a href="../files/npm-folders.html">npm-folders(5)</a></li>
302 <table border=0 cellspacing=0 cellpadding=0 id=npmlogo>
303 <tr><td style="width:180px;height:10px;background:rgb(237,127,127)" colspan=18> </td></tr>
304 <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>
305 <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>
306 <tr><td style="width:10px;height:10px;background:#fff" rowspan=2> </td></tr>
307 <tr><td style="width:10px;height:10px;background:#fff"> </td></tr>
308 <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>
309 <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>
311 <p id="footer">npm-faq — npm@2.14.4</p>
projects / platform / upstream / nodejs.git / blob