Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 267 lines (173 sloc) 8.356 kB
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
1 npm(1) -- node package manager
2 ==============================
4626dfa Initial drop. Ugly, sketchy, and not even yet quite a "work in progr…
isaacs authored
3
32f2673 @isaacs Add README as proper html/manpage doc
isaacs authored
4 ## SYNOPSIS
5
069a27c @isaacs Add a simpler install process up near the top.
isaacs authored
6 This is just enough info to get you up and running.
b3f1673 @isaacs another note pointing users to the documentation
isaacs authored
7
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
8 Much more info available via `npm help` once it's installed.
841f3b5 @isaacs Move the installing section up to the top
isaacs authored
9
266f1c9 @isaacs Update the README with more helpful info.
isaacs authored
10 ## IMPORTANT
11
b16093e @isaacs Make readme a bit more accurate
isaacs authored
12 **You need node v0.6 or higher to run this program.**
266f1c9 @isaacs Update the README with more helpful info.
isaacs authored
13
492dff3 @isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
14 To install an old **and unsupported** version of npm that works on node 0.3
199cb34 @isaacs Don't suggest how to use old versions
isaacs authored
15 and prior, clone the git repo and dig through the old tags and branches.
266f1c9 @isaacs Update the README with more helpful info.
isaacs authored
16
b16093e @isaacs Make readme a bit more accurate
isaacs authored
17 ## Super Easy Install
841f3b5 @isaacs Move the installing section up to the top
isaacs authored
18
b16093e @isaacs Make readme a bit more accurate
isaacs authored
19 npm comes with node now.
d49a887 @isaacs add some more installation suggestions/options
isaacs authored
20
b16093e @isaacs Make readme a bit more accurate
isaacs authored
21 ### Windows Computers
36b4215 @isaacs Add clean=yes/no instructions to README
isaacs authored
22
b16093e @isaacs Make readme a bit more accurate
isaacs authored
23 Get the MSI. npm is in it.
36b4215 @isaacs Add clean=yes/no instructions to README
isaacs authored
24
b16093e @isaacs Make readme a bit more accurate
isaacs authored
25 ### Apple Macintosh Computers
36b4215 @isaacs Add clean=yes/no instructions to README
isaacs authored
26
b16093e @isaacs Make readme a bit more accurate
isaacs authored
27 Get the pkg. npm is in it.
1c71826 @isaacs Update windows install instructions
isaacs authored
28
b16093e @isaacs Make readme a bit more accurate
isaacs authored
29 ### Other Sorts of Unices
1c71826 @isaacs Update windows install instructions
isaacs authored
30
b16093e @isaacs Make readme a bit more accurate
isaacs authored
31 Run `make install`. npm will be installed with node.
1c71826 @isaacs Update windows install instructions
isaacs authored
32
b16093e @isaacs Make readme a bit more accurate
isaacs authored
33 If you want a more fancy pants install (a different version, customized
34 paths, etc.) then read on.
1c71826 @isaacs Update windows install instructions
isaacs authored
35
b16093e @isaacs Make readme a bit more accurate
isaacs authored
36 ## Fancy Install (Unix)
ac51a71 @isaacs Update node version requirement for Windows
isaacs authored
37
b16093e @isaacs Make readme a bit more accurate
isaacs authored
38 To install npm with one command, do this:
1c71826 @isaacs Update windows install instructions
isaacs authored
39
b16093e @isaacs Make readme a bit more accurate
isaacs authored
40 curl http://npmjs.org/install.sh | sh
1c71826 @isaacs Update windows install instructions
isaacs authored
41
b16093e @isaacs Make readme a bit more accurate
isaacs authored
42 To skip the npm 0.x cleanup, do this:
1c71826 @isaacs Update windows install instructions
isaacs authored
43
b16093e @isaacs Make readme a bit more accurate
isaacs authored
44 curl http://npmjs.org/install.sh | clean=no sh
1c71826 @isaacs Update windows install instructions
isaacs authored
45
b16093e @isaacs Make readme a bit more accurate
isaacs authored
46 To say "yes" to the 0.x cleanup, but skip the prompt:
543790f @isaacs Update install instructions
isaacs authored
47
b16093e @isaacs Make readme a bit more accurate
isaacs authored
48 curl http://npmjs.org/install.sh | clean=yes sh
543790f @isaacs Update install instructions
isaacs authored
49
b16093e @isaacs Make readme a bit more accurate
isaacs authored
50 If you get permission errors, you'll need to **run** the script as root.
51 (Note, just putting `sudo` in front of the `curl` will **fetch** the script
52 as root.)
1c71826 @isaacs Update windows install instructions
isaacs authored
53
b16093e @isaacs Make readme a bit more accurate
isaacs authored
54 ### Slightly Fancier
1c71826 @isaacs Update windows install instructions
isaacs authored
55
b16093e @isaacs Make readme a bit more accurate
isaacs authored
56 You can set any npm configuration params with that script:
1c71826 @isaacs Update windows install instructions
isaacs authored
57
b16093e @isaacs Make readme a bit more accurate
isaacs authored
58 curl http://npmjs.org/install.sh | npm_config_prefix=/some/path sh
1c71826 @isaacs Update windows install instructions
isaacs authored
59
b16093e @isaacs Make readme a bit more accurate
isaacs authored
60 Or, you can run it in uber-debuggery mode:
1c71826 @isaacs Update windows install instructions
isaacs authored
61
b16093e @isaacs Make readme a bit more accurate
isaacs authored
62 curl http://npmjs.org/install.sh | npm_debug=1 sh
1c71826 @isaacs Update windows install instructions
isaacs authored
63
b16093e @isaacs Make readme a bit more accurate
isaacs authored
64 ### Even Fancier
1c71826 @isaacs Update windows install instructions
isaacs authored
65
b16093e @isaacs Make readme a bit more accurate
isaacs authored
66 Get the code with git. Use `make` to build the docs and do other stuff.
67 If you plan on hacking on npm, `make link` is your friend.
6740f2a @isaacs Add 'curl|sudo sh' instructions
isaacs authored
68
b16093e @isaacs Make readme a bit more accurate
isaacs authored
69 If you've got the npm source code, you can also semi-permanently set
70 arbitrary config keys using the `./configure --key=val ...`, and then
71 run npm commands by doing `node cli.js <cmd> <args>`. (This is helpful
72 for testing, or running stuff without actually installing npm itself.)
6740f2a @isaacs Add 'curl|sudo sh' instructions
isaacs authored
73
b16093e @isaacs Make readme a bit more accurate
isaacs authored
74 ## Fancy Windows Install
6740f2a @isaacs Add 'curl|sudo sh' instructions
isaacs authored
75
b16093e @isaacs Make readme a bit more accurate
isaacs authored
76 You can download a zip file from <http://npmjs.org/dist/>, and unpack it
77 in the same folder where node.exe lives.
543790f @isaacs Update install instructions
isaacs authored
78
b16093e @isaacs Make readme a bit more accurate
isaacs authored
79 If that's not fancy enough for you, then you can fetch the code with
80 git, and mess with it directly.
543790f @isaacs Update install instructions
isaacs authored
81
1c71826 @isaacs Update windows install instructions
isaacs authored
82 ## Installing on Cygwin
83
b3dcb9b @isaacs Update the README with better permission windows stuff
isaacs authored
84 No.
1c71826 @isaacs Update windows install instructions
isaacs authored
85
6740f2a @isaacs Add 'curl|sudo sh' instructions
isaacs authored
86 ## Dev Install
87
88 To install the latest **unstable** development version from git:
5d6fb4b @isaacs the install script sometimes fails.
isaacs authored
89
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
90 git clone https://github.com/isaacs/npm.git
91 cd npm
b3dcb9b @isaacs Update the README with better permission windows stuff
isaacs authored
92 git submodule update --init --recursive
543790f @isaacs Update install instructions
isaacs authored
93 sudo make install # (or: `node cli.js install -gf`)
5d6fb4b @isaacs the install script sometimes fails.
isaacs authored
94
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
95 If you're sitting in the code folder reading this document in your
96 terminal, then you've already got the code. Just do:
97
b3dcb9b @isaacs Update the README with better permission windows stuff
isaacs authored
98 git submodule update --init --recursive
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
99 sudo make install
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
100
101 and npm will install itself.
102
b3dcb9b @isaacs Update the README with better permission windows stuff
isaacs authored
103 Note that github tarballs **do not contain submodules**, so
492dff3 @isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
104 those won't work. You'll have to also fetch the appropriate submodules
105 listed in the .gitmodules file.
106
b3dcb9b @isaacs Update the README with better permission windows stuff
isaacs authored
107 ## Permissions when Using npm to Install Other Stuff
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
108
8ee3c3e @isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
109 **tl;dr**
110
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
111 * Use `sudo` for greater safety. Or don't, if you prefer not to.
8ee3c3e @isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
112 * npm will downgrade permissions if it's root before running any build
113 scripts that package authors specified.
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
114
678d2e8 @isaacs change readme to suggest root usage
isaacs authored
115 ### More details...
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
116
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
117 As of version 0.3, it is recommended to run npm as root.
678d2e8 @isaacs change readme to suggest root usage
isaacs authored
118 This allows npm to change the user identifier to the `nobody` user prior
119 to running any package build or test commands.
3901ac1 @isaacs Be more specific with the chown instructions
isaacs authored
120
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
121 If you are not the root user, or if you are on a platform that does not
122 support uid switching, then npm will not attempt to change the userid.
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
123
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
124 If you would like to ensure that npm **always** runs scripts as the
125 "nobody" user, and have it fail if it cannot downgrade permissions, then
126 set the following configuration param:
d49a887 @isaacs add some more installation suggestions/options
isaacs authored
127
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
128 npm config set unsafe-perm false
069a27c @isaacs Add a simpler install process up near the top.
isaacs authored
129
78a05bb Added syntax highlighting for codeblocks (README.md).
Zearin authored
130 This will prevent running in unsafe mode, even as non-root users.
069a27c @isaacs Add a simpler install process up near the top.
isaacs authored
131
c71ae65 @isaacs version notes for 0.1.11
isaacs authored
132 ## Uninstalling
133
134 So sad to see you go.
135
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
136 sudo npm uninstall npm -g
c71ae65 @isaacs version notes for 0.1.11
isaacs authored
137
138 Or, if that fails,
139
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
140 sudo make uninstall
d9e9c14 @isaacs Point developers to the docs
isaacs authored
141
c7dee39 @isaacs Add npm removal instructions
isaacs authored
142 ## More Severe Uninstalling
143
144 Usually, the above instructions are sufficient. That will remove
145 npm, but leave behind anything you've installed.
146
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
147 If you would like to remove all the packages that you have installed,
148 then you can use the `npm ls` command to find them, and then `npm rm` to
149 remove them.
c7dee39 @isaacs Add npm removal instructions
isaacs authored
150
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
151 To remove cruft left behind by npm 0.x, you can use the included
152 `clean-old.sh` script file. You can run it conveniently like this:
c7dee39 @isaacs Add npm removal instructions
isaacs authored
153
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
154 npm explore npm -g -- sh scripts/clean-old.sh
c7dee39 @isaacs Add npm removal instructions
isaacs authored
155
a26fb09 @isaacs Config removal instructions
isaacs authored
156 npm uses two configuration files, one for per-user configs, and another
157 for global (every-user) configs. You can view them by doing:
158
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
159 npm config get userconfig # defaults to ~/.npmrc
160 npm config get globalconfig # defaults to /usr/local/etc/npmrc
a26fb09 @isaacs Config removal instructions
isaacs authored
161
162 Uninstalling npm does not remove configuration files by default. You
163 must remove them yourself manually if you want them gone. Note that
164 this means that future npm installs will not remember the settings that
165 you have chosen.
166
da8557a @isaacs document programmatic usage
isaacs authored
167 ## Using npm Programmatically
168
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
169 If you would like to use npm programmatically, you can do that.
78a05bb Added syntax highlighting for codeblocks (README.md).
Zearin authored
170 It's not very well documented, but it *is* rather simple.
171
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
172 var npm = require("npm")
173 npm.load(myConfigObject, function (er) {
174 if (er) return handlError(er)
175 npm.commands.install(["some", "args"], function (er, data) {
176 if (er) return commandFailed(er)
177 // command succeeded, and data might have some info
178 })
179 npm.on("log", function (message) { .... })
180 })
da8557a @isaacs document programmatic usage
isaacs authored
181
701a821 @isaacs Confusion about args vs conf
isaacs authored
182 The `load` function takes an object hash of the command-line configs.
183 The various `npm.commands.<cmd>` functions take an **array** of
184 positional argument **strings**. The last argument to any
185 `npm.commands.<cmd>` function is a callback. Some commands take other
186 optional arguments. Read the source.
187
188 You cannot set configs individually for any single npm function at this
189 time. Since `npm` is a singleton, any call to `npm.config.set` will
190 change the value for *all* npm commands in that process.
191
4eb8f6b @isaacs Avoid accidentally opening npm.js with WSH
isaacs authored
192 See `./bin/npm-cli.js` for an example of pulling config values off of the
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
193 command line arguments using nopt. You may also want to check out `npm
194 help config` to learn about all the options you can set there.
266f1c9 @isaacs Update the README with more helpful info.
isaacs authored
195
d9e9c14 @isaacs Point developers to the docs
isaacs authored
196 ## More Docs
197
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
198 Check out the [docs](http://npmjs.org/doc/),
b16093e @isaacs Make readme a bit more accurate
isaacs authored
199 especially the [faq](http://npmjs.org/doc/faq.html).
d9e9c14 @isaacs Point developers to the docs
isaacs authored
200
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
201 You can use the `npm help` command to read any of them.
5885cbf @isaacs Update readme to reference super duper easy install script.
isaacs authored
202
d9e9c14 @isaacs Point developers to the docs
isaacs authored
203 If you're a developer, and you want to use npm to publish your program,
204 you should
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
205 [read this](http://npmjs.org/doc/developers.html)
492dff3 @isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
206
207 ## Legal Stuff
208
209 "npm" and "the npm registry" are owned by Isaac Z. Schlueter. All
210 rights not explicitly granted in the MIT license are reserved. See the
211 included LICENSE file for more details.
212
213 "Node.js" and "node" are trademarks owned by Joyent, Inc. npm is not
214 officially part of the Node.js project, and is neither owned by nor
215 officially affiliated with Joyent, Inc.
216
217 The packages in the npm registry are not part of npm itself, and are the
218 sole property of their respective maintainers. While every effort is
219 made to ensure accountability, there is absolutely no guarantee,
220 warrantee, or assertion made as to the quality, fitness for a specific
221 purpose, or lack of malice in any given npm package. Modules
222 published on the npm registry are not affiliated with or endorsed by
223 Joyent, Inc., Isaac Z. Schlueter, Ryan Dahl, or the Node.js project.
224
225 If you have a complaint about a package in the npm registry, and cannot
226 resolve it with the package owner, please express your concerns to
227 Isaac Z. Schlueter at <i@izs.me>.
228
229 ### In plain english
230
231 This is mine; not my employer's, not Node's, not Joyent's, not Ryan
232 Dahl's.
233
234 If you publish something, it's yours, and you are solely accountable
235 for it. Not me, not Node, not Joyent, not Ryan Dahl.
236
237 If other people publish something, it's theirs. Not mine, not Node's,
238 not Joyent's, not Ryan Dahl's.
239
240 Yes, you can publish something evil. It will be removed promptly if
241 reported, and we'll lose respect for you. But there is no vetting
242 process for published modules.
243
244 If this concerns you, inspect the source before using packages.
32f2673 @isaacs Add README as proper html/manpage doc
isaacs authored
245
b16093e @isaacs Make readme a bit more accurate
isaacs authored
246 ## BUGS
247
248 When you find issues, please report them:
249
250 * web:
251 <http://github.com/isaacs/npm/issues>
252 * email:
253 <npm-@googlegroups.com>
254
255 Be sure to include *all* of the output from the npm command that didn't work
256 as expected. The `npm-debug.log` file is also helpful to provide.
257
258 You can also look for isaacs in #node.js on irc://irc.freenode.net. He
259 will no doubt tell you to put the output in a gist or email.
260
32f2673 @isaacs Add README as proper html/manpage doc
isaacs authored
261 ## SEE ALSO
262
263 * npm(1)
264 * npm-faq(1)
265 * npm-help(1)
4dc1095 @isaacs Add some see-also links to npm-index(1)
isaacs authored
266 * npm-index(1)
Something went wrong with that request. Please try again.