1 .\" Generated with Ronnjs 0.3.8
2 .\" http://github.com/kapouer/ronnjs/
4 .TH "NPM\-FAQ" "7" "December 2013" "" ""
7 \fBnpm-faq\fR \-\- Frequently Asked Questions
9 .SH "Where can I find these docs in HTML?"
10 \fIhttps://npmjs\.org/doc/\fR, or run:
15 npm config set viewer browser
22 to open these documents in your default web browser rather than \fBman\fR\|\.
24 .SH "It didn't work\."
25 That\'s not really a question\.
27 .SH "Why didn't it work?"
31 Read the error output, and if you can\'t figure out what it means,
32 do what it says and post a bug with all the information it asks for\.
34 .SH "Where does npm put stuff?"
35 npm help See \fBnpm\-folders\fR
41 Use the \fBnpm root\fR command to see where modules go, and the \fBnpm bin\fR
42 command to see where executables go
45 Global installs are different from local installs\. If you install
46 something with the \fB\-g\fR flag, then its executables go in \fBnpm bin \-g\fR
47 and its modules go in \fBnpm root \-g\fR\|\.
51 .SH "How do I install something on my computer in a central location?"
52 Install it globally by tacking \fB\-g\fR or \fB\-\-global\fR to the command\. (This
53 is especially important for command line utilities that need to add
54 their bins to the global system \fBPATH\fR\|\.)
56 .SH "I installed something globally, but I can't "
60 The global install location is a place for command\-line utilities
61 to put their bins in the system \fBPATH\fR\|\. It\'s not for use with \fBrequire()\fR\|\.
64 If you \fBrequire()\fR a module in your code, then that means it\'s a
65 dependency, and a part of your program\. You need to install it locally
68 .SH "Why can't npm just put everything in one place, like other package managers?"
69 Not every change is an improvement, but every improvement is a change\.
70 This would be like asking git to do network IO for every commit\. It\'s
71 not going to happen, because it\'s a terrible idea that causes more
72 problems than it solves\.
75 It is much harder to avoid dependency conflicts without nesting
76 dependencies\. This is fundamental to the way that npm works, and has
77 npm help proven to be an extremely successful approach\. See \fBnpm\-folders\fR for
81 If you want a package to be installed in one place, and have all your
82 programs reference the same copy of it, then use the \fBnpm link\fR command\.
83 That\'s what it\'s for\. Install it globally, then link it into each
84 program that uses it\.
86 .SH "Whatever, I really want the old style 'everything global' style\."
87 Write your own package manager, then\. It\'s not that hard\.
90 npm will not help you do something that is known to be a bad idea\.
92 .SH "Should I check my "
93 Mikeal Rogers answered this question very well:
96 \fIhttp://www\.mikealrogers\.com/posts/nodemodules\-in\-git\.html\fR
102 Check \fBnode_modules\fR into git for things you \fBdeploy\fR, such as
106 Do not check \fBnode_modules\fR into git for libraries and modules
107 intended to be reused\.
110 Use npm to manage dependencies in your dev environment, but not in
111 your deployment scripts\.
115 .SH "Is it 'npm' or 'NPM' or 'Npm'?"
116 npm should never be capitalized unless it is being displayed in a
117 location that is customarily all\-caps (such as the title of man pages\.)
119 .SH "If 'npm' is an acronym, why is it never capitalized?"
120 Contrary to the belief of many, "npm" is not in fact an abbreviation for
121 "Node Package Manager"\. It is a recursive bacronymic abbreviation for
122 "npm is not an acronym"\. (If it was "ninaa", then it would be an
123 acronym, and thus incorrectly named\.)
126 "NPM", however, \fIis\fR an acronym (more precisely, a capitonym) for the
127 National Association of Pastoral Musicians\. You can learn more
128 about them at \fIhttp://npm\.org/\fR\|\.
131 In software, "NPM" is a Non\-Parametric Mapping utility written by
132 Chris Rorden\. You can analyze pictures of brains with it\. Learn more
133 about the (capitalized) NPM program at \fIhttp://www\.cabiatl\.com/mricro/npm/\fR\|\.
136 The first seed that eventually grew into this flower was a bash utility
137 named "pm", which was a shortened descendent of "pkgmakeinst", a
138 bash function that was used to install various different things on different
139 platforms, most often using Yahoo\'s \fByinst\fR\|\. If \fBnpm\fR was ever an
140 acronym for anything, it was \fBnode pm\fR or maybe \fBnew pm\fR\|\.
143 So, in all seriousness, the "npm" project is named after its command\-line
144 utility, which was organically selected to be easily typed by a right\-handed
145 programmer using a US QWERTY keyboard layout, ending with the
146 right\-ring\-finger in a postition to type the \fB\-\fR key for flags and
147 other command\-line arguments\. That command\-line utility is always
148 lower\-case, though it starts most sentences it is a part of\.
150 .SH "How do I list installed packages?"
153 .SH "How do I search for packages?"
157 Arguments are greps\. \fBnpm search jsdom\fR shows jsdom packages\.
159 .SH "How do I update npm?"
167 You can also update all outdated local packages by doing \fBnpm update\fR without
168 any arguments, or global packages by doing \fBnpm update \-g\fR\|\.
171 Occasionally, the version of npm will progress such that the current
172 version cannot be properly installed with the version that you have
173 installed already\. (Consider, if there is ever a bug in the \fBupdate\fR
177 In those cases, you can do this:
182 curl https://npmjs\.org/install\.sh | sh
192 a) a folder containing a program described by a package\.json file
195 b) a gzipped tarball containing (a)
198 c) a url that resolves to (b)
201 d) a \fB<name>@<version>\fR that is published on the registry with (c)
204 e) a \fB<name>@<tag>\fR that points to (d)
207 f) a \fB<name>\fR that has a "latest" tag satisfying (e)
210 g) a \fBgit\fR url that, when cloned, results in (a)\.
215 Even if you never publish your package, you can still get a lot of
216 benefits of using npm if you just want to write a node program (a), and
217 perhaps if you also want to be able to easily install it elsewhere
218 after packing it up into a tarball (b)\.
221 Git urls can be of the form:
226 git://github\.com/user/project\.git#commit\-ish
227 git+ssh://user@hostname:project\.git#commit\-ish
228 git+http://user@hostname/project/blah\.git#commit\-ish
229 git+https://user@hostname/project/blah\.git#commit\-ish
236 The \fBcommit\-ish\fR can be any tag, sha, or branch which can be supplied as
237 an argument to \fBgit checkout\fR\|\. The default is \fBmaster\fR\|\.
240 A module is anything that can be loaded with \fBrequire()\fR in a Node\.js
241 program\. The following things are all examples of things that can be
245 A folder with a \fBpackage\.json\fR file containing a \fBmain\fR field\.
248 A folder with an \fBindex\.js\fR file in it\.
256 Most npm packages are modules, because they are libraries that you
257 load with \fBrequire\fR\|\. However, there\'s no requirement that an npm
258 package be a module! Some only contain an executable command\-line
259 interface, and don\'t provide a \fBmain\fR field for use in Node programs\.
262 Almost all npm packages (at least, those that are Node programs) \fIcontain\fR many modules within them (because every file they load with \fBrequire()\fR is a module)\.
265 In the context of a Node program, the \fBmodule\fR is also the thing that
266 was loaded \fIfrom\fR a file\. For example, in the following program:
271 var req = require(\'request\')
278 we might say that "The variable \fBreq\fR refers to the \fBrequest\fR module"\.
280 .SH "So, why is it the ""
281 The \fBpackage\.json\fR file defines the package\. (See "What is a
285 The \fBnode_modules\fR folder is the place Node\.js looks for modules\.
286 (See "What is a module?" above\.)
289 For example, if you create a file at \fBnode_modules/foo\.js\fR and then
290 had a program that did \fBvar f = require(\'foo\.js\')\fR then it would load
291 the module\. However, \fBfoo\.js\fR is not a "package" in this case,
292 because it does not have a package\.json\.
295 Alternatively, if you create a package which does not have an \fBindex\.js\fR or a \fB"main"\fR field in the \fBpackage\.json\fR file, then it is
296 not a module\. Even if it\'s installed in \fBnode_modules\fR, it can\'t be
297 an argument to \fBrequire()\fR\|\.
299 .SH "<code>"node_modules"</code>"
300 No\. This will never happen\. This question comes up sometimes,
301 because it seems silly from the outside that npm couldn\'t just be
302 configured to put stuff somewhere else, and then npm could load them
303 from there\. It\'s an arbitrary spelling choice, right? What\'s the big
307 At the time of this writing, the string \fB\'node_modules\'\fR appears 151
308 times in 53 separate files in npm and node core (excluding tests and
312 Some of these references are in node\'s built\-in module loader\. Since
313 npm is not involved \fBat all\fR at run\-time, node itself would have to
314 be configured to know where you\'ve decided to stick stuff\. Complexity
315 hurdle #1\. Since the Node module system is locked, this cannot be
316 changed, and is enough to kill this request\. But I\'ll continue, in
317 deference to your deity\'s delicate feelings regarding spelling\.
320 Many of the others are in dependencies that npm uses, which are not
321 necessarily tightly coupled to npm (in the sense that they do not read
322 npm\'s configuration files, etc\.) Each of these would have to be
323 configured to take the name of the \fBnode_modules\fR folder as a
324 parameter\. Complexity hurdle #2\.
327 Furthermore, npm has the ability to "bundle" dependencies by adding
328 the dep names to the \fB"bundledDependencies"\fR list in package\.json,
329 which causes the folder to be included in the package tarball\. What
330 if the author of a module bundles its dependencies, and they use a
331 different spelling for \fBnode_modules\fR? npm would have to rename the
332 folder at publish time, and then be smart enough to unpack it using
333 your locally configured name\. Complexity hurdle #3\.
336 Furthermore, what happens when you \fIchange\fR this name? Fine, it\'s
337 easy enough the first time, just rename the \fBnode_modules\fR folders to \fB\|\./blergyblerp/\fR or whatever name you choose\. But what about when you
338 change it again? npm doesn\'t currently track any state about past
339 configuration settings, so this would be rather difficult to do
340 properly\. It would have to track every previous value for this
341 config, and always accept any of them, or else yesterday\'s install may
342 be broken tomorrow\. Complexity hurdle #5\.
345 Never going to happen\. The folder is named \fBnode_modules\fR\|\. It is
346 written indelibly in the Node Way, handed down from the ancient times
349 .SH "How do I install node with npm?"
350 You don\'t\. Try one of these node version managers:
356 \fIhttp://github\.com/isaacs/nave\fR
359 \fIhttp://github\.com/visionmedia/n\fR
362 \fIhttp://github\.com/creationix/nvm\fR
370 \fIhttp://github\.com/marcelklehr/nodist\fR
373 \fIhttps://github\.com/hakobera/nvmw\fR
376 \fIhttps://github\.com/nanjingboy/nvmw\fR
380 .SH "How can I use npm for development?"
381 npm help See \fBnpm\-developersnpm help \fR and \fBpackage\.json\fR\|\.
384 You\'ll most likely want to \fBnpm link\fR your development folder\. That\'s
388 npm help To set up your own private registry, check out \fBnpm\-registry\fR\|\.
390 .SH "Can I list a url as a dependency?"
391 Yes\. It should be a url to a gzipped tarball containing a single folder
392 that has a package\.json in its root, or a git url\.
393 (See "what is a package?" above\.)
395 .SH "How do I symlink to a dev folder so I don't have to keep re\-installing?"
396 npm help See \fBnpm\-link\fR
398 .SH "The package registry website\. What is that exactly?"
399 npm help See \fBnpm\-registry\fR\|\.
401 .SH "I forgot my password, and can't publish\. How do I reset it?"
402 Go to \fIhttps://npmjs\.org/forgot\fR\|\.
404 .SH "I get ECONNREFUSED a lot\. What's up?"
405 Either the registry is down, or node\'s DNS isn\'t able to reach out\.
408 To check if the registry is down, open up \fIhttp://registry\.npmjs\.org/\fR
409 in a web browser\. This will also tell you if you are just unable to
410 access the internet for some reason\.
413 If the registry IS down, let me know by emailing \fIi@izs\.me\fR or posting
414 an issue at \fIhttps://github\.com/isaacs/npm/issues\fR\|\. We\'ll have
415 someone kick it or something\.
417 .SH "Why no namespaces?"
418 Please see this discussion: \fIhttps://github\.com/isaacs/npm/issues/798\fR
421 tl;dr \- It doesn\'t actually make things better, and can make them worse\.
424 If you want to namespace your own packages, you may: simply use the \fB\-\fR character to separate the names\. npm is a mostly anarchic system\.
425 There is not sufficient need to impose namespace rules on everyone\.
428 \fBnpm view npm author\fR
431 \fBnpm view npm contributors\fR
433 .SH "I have a question or request not addressed here\. Where should I put it?"
434 Post an issue on the github project:
437 \fIhttps://github\.com/isaacs/npm/issues\fR
441 .SH "Why does npm hate me?"
442 npm is not capable of hatred\. It loves everyone, especially you\.
453 npm help package\.json
projects / platform / upstream / nodejs.git / blob